Metadata-Version: 2.4
Name: pseudohub
Version: 0.1.0
Summary: Fetch pseudopotential files from Pseudo-Dojo
Author-email: Brent Hu <hyxbrent@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/brtboi/pseudohub
Project-URL: Repository, https://github.com/brtboi/pseudohub
Project-URL: Issues, https://github.com/brtboi/pseudohub/issues
Keywords: pseudopotential,dft,materials-science,quantum-espresso
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Requires-Dist: platformdirs>=3.0
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-mock>=3.10; extra == "test"
Dynamic: license-file

# pseudohub

Fetch pseudopotential files from [Pseudo-Dojo](https://www.pseudo-dojo.org)
(and, eventually, other providers) — usable as a Python library or a CLI.

## Install

```bash
pip install -e .
```

## Library usage

```python
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",
)

# 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:

```python
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

```bash
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

```bash
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`.
