Metadata-Version: 2.4
Name: milady-mlip
Version: 2.0.1
Summary: Python launcher for the MiLaDy machine-learning interatomic potential solver
Author-email: Cosmin Marinica <mihai-cosmin.marinica@cea.fr>
License: LicenseRef-MILADY
Project-URL: Homepage, https://codev-tuleap.intra.cea.fr/plugins/git/milady
Keywords: milady,machine-learning,interatomic-potential,MLIP,materials
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: mkl<2025.0,>=2024.2
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Dynamic: requires-dist

# milady — Python launcher for the MiLaDy solver

`milady_run(...)` stages a working directory and runs
`mpirun -np N milady_main.exe` in it, so a MiLaDy run becomes one Python call.

```python
from milady import milady_run

res = milady_run(
    input="/path/to/vacancy.ml",          # the .ml namelist
    db_model="/path/to/db_model.in",       # the db_model table
    DB="/path/to/MPtrj_2022.9_full.json",  # database: .json / .xyz file, or a classic DB dir
    nprocs=4,
)

print(res.returncode, res.duration_s, res.workdir)
for f in res.output_files:                 # files the run created / changed
    print(f)
```

Equivalent on the command line:

```console
$ milady-run -i vacancy.ml -m db_model.in -d MPtrj_2022.9_full.json -n 4
```

## What it does

The solver always runs *inside a directory* and reads fixed names from it.
`milady_run` builds that directory for you:

| staged file  | source            | name used                                   |
|--------------|-------------------|---------------------------------------------|
| `name.in`    | derived           | one line: the run *stem* (e.g. `vacancy`)   |
| `<stem>.ml`  | `input=`          | stem from `input`'s basename, or `name=`    |
| `<db_file>`  | `db_model=`       | `db_file=` in the `.ml` (default `db_model.in`) |
| `<db_path>`  | `DB=`             | `db_path=` in the `.ml`; else `DB` for a directory (classic `DB/`), else the file's basename |

The database is **symlinked** by default (it can be tens of GB); pass
`copy_db=True` to copy it. Small text inputs are copied. Extra auxiliary inputs
(`*.gin`, `train_files.milady`, …) go through `extra_files=[...]`.

## Finding the solver

Resolution order (first hit wins):

1. `exe=` / `mpirun=` arguments
2. `$MILADY_EXE` / `$MILADY_MPIRUN`
3. `milady_main.exe` / `mpirun` on `PATH` (the case after `conda install milady`)
4. `$CONDA_PREFIX/bin`, then `$MLD_BUIDIR/bin` (and `_gnu` / `_intel` / `_mix` variants)

Runtime shared libraries: `$MILADY_LIB` (a `:`-list) if set, otherwise the
conda prefix the solver lives in plus whatever `ldd` currently resolves — these
are prepended to `LD_LIBRARY_PATH` for the child process only.

## Key options

| argument         | default            | meaning |
|------------------|--------------------|---------|
| `nprocs`         | `1`                | MPI ranks (`mpirun -np`) |
| `workdir`        | fresh temp dir     | where to run; **not** deleted afterwards |
| `name`           | from `input`       | run stem |
| `mpi_args`       | `()`               | extra launcher tokens, e.g. `["--oversubscribe"]` |
| `env`            | `None`             | extra environment for the run |
| `use_mpirun`     | `None`             | `None` = auto (launcher if found or `nprocs>1`) |
| `stream_output`  | `False`            | also echo solver output live |
| `check`          | `True`             | raise `MiladyError` on non-zero exit |
| `timeout`        | `None`             | seconds before the run is killed |
| `log_file`       | `"milady.out"`     | combined stdout+stderr log written in `workdir` |
| `output`         | `None`             | extra combined-log path (abs, or relative to CWD), e.g. `run.out` |

## Install

The **PyPI distribution name is `milady-mlip`**; the import name stays `milady`.

| want | command | contents |
|---|---|---|
| solver + launcher, no toolchain | `pip install milady-mlip` | self-contained wheel (Linux x86-64); pulls `mkl` |
| solver + launcher, via conda | `conda install -c <ch> milady` | `milady` + `milady-bin` (see `../conda/`) |
| launcher only (you supply `milady_main.exe`) | `pip install ./python` | pure Python, any OS |

The self-contained wheel is built by [`wheel/build_wheel.sh`](wheel/build_wheel.sh)
(desktop) or the `wheels` GitHub Actions workflow (manylinux, PyPI-ready) — see
[`wheel/README.md`](wheel/README.md).
