pseudohub

Fetch pseudopotential files from Pseudo-Dojo (and, eventually, other providers) — usable as a Python library or a CLI.

Install

pip install -e .

Library usage

from pseudohub import get_pseudo, get_pseudo_table, get_hints

# nc, sr, pbe, standard, upf, newest version, cached in the default
# per-user cache directory
path = get_pseudo("Si")

path = get_pseudo(
    14, kind="paw", generator="pbesol", accuracy="stringent",
    format="psp8", cache_dir="/scratch/me/pseudos",
)

# also save (not just cache) a copy somewhere specific -- a directory
# keeps the original filename, a full path lets you rename
get_pseudo("Si", output=".")           # ./Si.upf
get_pseudo("Si", output="Si.upf")      # explicit filename, any directory

# recommended plane-wave energy cutoff (Ha)
hints = get_hints("Si", level="high")
print(hints["ecut"])

# full table archive for every element
table_dir = get_pseudo_table(kind="nc", generator="pbe", accuracy="standard")

An invalid parameter combination raises InvalidParameterError with suggestions for the closest real option:

get_pseudo("Fe", kind="paw", generator="pw", accuracy="stringent")
# InvalidParameterError: No Pseudo-Dojo table for kind='paw', relativity='sr',
# version=None, generator='pw', accuracy='stringent'.
# did you mean one of:
#   - paw_pw_standard

CLI usage

pseudohub get Si --kind nc --generator pbesol --accuracy stringent --format psp8
pseudohub table --kind paw --generator pbe --accuracy standard --table-format upf
pseudohub hints Si --level high
pseudohub get La --version 04-3plus --format upf   # lanthanide semicore table

Global flags (get/table/hints all accept them, placed before the subcommand): --provider, --cache-dir, --no-cache, --force.

Caching

Downloads are cached by default in a per-user cache directory (via platformdirs, e.g. ~/.cache/pseudohub on Linux), so repeated calls across projects reuse files instead of re-downloading. Use cache_dir=/--cache-dir to point at your own location (e.g. shared HPC scratch space), or cache=False/--no-cache to skip caching entirely.

Development

pip install -e ".[test]"
pytest

Tests are fully offline — network calls are mocked at the requests.get seam in pseudohub.cache.

Adding a new provider

1. Create src/pseudohub/providers/<name>.py with a class implementing pseudohub.providers.base.Provider (get_pseudo, optionally get_table / get_hints).
2. Register it in src/pseudohub/providers/__init__.py's PROVIDER_REGISTRY.
3. It's now available via get_pseudo(..., provider="<name>") and pseudohub --provider <name> get .... Provider-specific parameters don't need to match any other provider's — get_pseudo's **kwargs pass straight through, and an unsupported kwarg raises a normal TypeError.