Configuration¶
Most of the time you will set everything on the command line. When runs get
more involved you can move settings into a settings.ini, a model alias or an
INCAR-style job file. They all feed one resolver, which applies the layers in
this order, each overriding the one before:
built-in defaults
< settings.ini
< model alias ([model:NAME])
< profile ([profile:NAME])
< INCAR / job file
< CLI flags / API arguments
The resolver never merges two layers' ideas of an option. Each option ends up
with exactly one value from exactly one source, and that source is written to
resolved_config.json (see Output files). When you wonder why a
run behaved as it did, that file has the answer.
What a run needs¶
| What | Where it comes from |
|---|---|
| calculation type | the subcommand (sp, opt, md, neb, batch, confsearch), or CALC_TYPE / CALCULATION |
| backend | --model-type / MODEL_TYPE, or a model alias that declares engine |
| model path | --model / MODEL_PATH, or the alias's path |
| structure | the positional argument, or --structure / the INCAR structure keys with run |
| DPA branch | --head / HEAD, when the checkpoint is multi-task |
| NEB endpoints | --initial / --final, or NEB_INITIAL / NEB_FINAL |
| confsearch starts | CS_STARTS + CS_ADSORBATE_INDICES, or --slab / --molecule / --n-starts |
There is no implicit UMA default, or any other. If no layer names a backend, the resolver stops:
Error: No MLIP backend was selected.
Choose one of:
--model-type mace
--model-type dpa
--model-type grace
--model-type uma
or use a configured model alias/profile.
Strict by default¶
A misspelled key, or a key that belongs to another backend, is a fatal error. The alternative — a warning and a run that carries on with the wrong settings — is exactly how a wrong result gets produced and trusted.
mliport sp structure.cif --model m.model --model-type mace --inference-mode turbo
# Error: Option 'inference_mode' is not applicable to engine 'mace' ...
For exploratory work you can switch to the old warn-and-continue behavior, but only on purpose:
To look at your configuration, use mliport config validate settings.ini to
check a file and mliport config explain <KEY> to see where one value came
from. mliport config paths lists where settings.ini is searched for,
mliport config init writes a starter file, mliport config show prints the
resolved configuration, and mliport config schema lists every recognized key.
settings.ini¶
The search paths, highest priority first, are printed by mliport config paths.
Set MLIPORT_SETTINGS to point at one explicit file; the global
--settings PATH flag beats even that.
[general]
strict_config = true
[model:mace_omat]
engine = mace
path = /models/mace-omat-0-medium.model
task = bulk
[md]
ensemble = NVT
temperature = 300
[profile:quick]
calc_type = sp
device = cuda
- A
[model:NAME]section must declareengine(uma,mace,dpaorgrace;fairchemis another name foruma). - A
[profile:NAME]section bundles calculator and run options without naming a model. - Sections named after a calculation type (
[sp],[md],[neb], …) set defaults for that type only.[general],[resources],[output]and[safety]apply everywhere.
INCAR-style jobs¶
mliport run --incar INCAR.mliport reads a key/value file in the style of a
VASP INCAR. It is only the style: this is not a DFT input. Every accepted key,
with its type, default, allowed values and applicability, is listed in the
INCAR key reference.
CALC_TYPE = SP
MODEL_TYPE = MACE
MODEL_PATH = /models/mace-omat-0-medium.model
DEVICE = cpu # explicit cuda / cuda:0 for GPU runs
Let mliport write a template, and fill in the backend yourself:
mliport template sp --engine mace --output INCAR.mace
mliport template sp --output INCAR.neutral # backend-neutral, MODEL_TYPE=REQUIRED
A task folder¶
The intended daily use is one folder per task: an INCAR.mliport next to the
structure file (POSCAR, CONTCAR, structure.cif or structure.xyz). Then
mliport run needs no arguments at all:
mliport run writes into results/ in the folder that holds the INCAR. That
default is a run-only convenience: --output and OUTPUT_DIR still win, a
relative OUTPUT_DIR is resolved against the INCAR folder rather than the
current directory, and OUTPUT_DIR = . restores the previous behaviour of
writing into the current directory (a relative OUTPUT_DIR from settings.ini
or the command line stays current-directory relative, as before). A results/ directory that already holds a
run is refused, as before, until you pass --overwrite.
CALC_TYPE = CONFSEARCH is accepted by mliport run and takes exactly the
same path as mliport confsearch run. CALC_TYPE = BATCH is not: use
mliport batch, which needs its own input directory.
Options that belong to one backend¶
| Option | Backend | What it does |
|---|---|---|
TASK / --task |
UMA | task family (omat, omol, oc20, …) |
TASK / --task |
MACE, DPA, GRACE | explicit PBC semantic (bulk / molecule) |
HEAD / --head |
DPA, MACE | checkpoint branch or head (default for many MACE models) |
INFERENCE_MODE |
UMA | default, turbo or trained inference preset |
ACTIVATION_CHECKPOINTING |
UMA | saves GPU memory |
DEFAULT_DTYPE |
MACE | model precision |
GPU_MEMORY_GROWTH, GPU_MEMORY_LIMIT_MB |
GRACE | TensorFlow GPU memory policy |
NEIGHBOR_CACHE, NEIGHBOR_SKIN |
GRACE | neighbor-list cache policy |
TORCH_NUM_THREADS |
UMA, MACE, DPA | CPU intra-op threads |
Handing one of these to a different backend is an error under strict configuration. The option is never silently dropped.
Dispersion correction (DFT-D3)¶
An MLIP checkpoint does not contain a dispersion correction. A model trained on
plain PBE data (MACE omat heads, UMA omat, most materials models) has learned
the PBE potential energy surface, which has no long-range dispersion. --d3
adds Grimme's DFT-D3 energy, forces and stress on top of the model, on every
backend, through torch-dftd:
| Option | Default | What it does |
|---|---|---|
D3 / --d3 |
off | add DFT-D3 to the model |
D3_XC / --d3-xc |
pbe |
reference functional of the model's training data; selects the D3 parameters |
D3_DAMPING / --d3-damping |
bj |
damping function: zero, bj, zerom or bjm |
uv pip install --python .venv-mace/bin/python torch-dftd
mliport opt slab.vasp --model model.model --model-type mace --task bulk --d3
Only add D3 to a model whose training reference has no dispersion, and name
that reference with --d3-xc; mliport cannot read it from a MACE, DPA or GRACE
checkpoint. For UMA the reference of each task is known: D3 is accepted for
omat (PBE) and oc20 (RPBE) only, and refused for omol, omc, odac and
oc25, whose references already contain dispersion or are not verified to be
dispersion-free. D3_XC or D3_DAMPING without D3 is an error rather than a
setting that silently does nothing. NEB does not accept D3 yet. In the TUI, the
DFT-D3 switch on the configuration screen sets the same three options (the NEB
form does not show it).
The correction is recorded with the run: dispersion in the model metadata of
the JSON output and a Dispersion: line in the OUTCAR-style header. The
torch-dftd package needs PyTorch, which the MACE, DPA and UMA environments
already have.
Model files: models/¶
Model weights are not part of mliport and never committed. Keep them in the
models/ directory at the root of the mliport checkout - it is in
.gitignore - and refer to a checkpoint by its file name:
A MODEL_PATH without any path separator is a file name, and mliport looks
it up in this order:
- a file of that name next to the INCAR (this is what an explicit path already did),
<MLIPORT_ROOT>/models/<name>,<MLIPORT_ROOT>/models/*/<name>, exactly one level of subdirectories.
Two files with that name in step 3 are an error rather than a coin flip: a
different checkpoint is a different model identity, so the choice has to be
made by you. A value that contains a path separator is a path and nothing else;
it is resolved against the file that declares it and is never redirected into
models/.
MLIPORT_ROOT is the mliport checkout itself. It comes from the
MLIPORT_ROOT environment variable; when that is unset, mliport accepts the
parent of sys.prefix if the interpreter runs from an installer-created
.venv-<engine> environment, whose bin/mliport-<engine> launcher exports it
for you. Without a root, a bare file name is refused with instructions instead
of being resolved against a guess. When a model cannot be found, the error
names every location that was searched and lists the files models/ does
contain.
mliport doctor reports the root it would use, the models/ directory and the
model files in it. The absolute path that was resolved is what
resolved_config.json records for every run.
Scientific defaults¶
Defaults for temperature, timestep, step counts, thermostat, optimizer, fmax,
NEB settings and so on live in mliport's built-in defaults, are scoped to the
calculation type, and are recorded for every run in resolved_config.json.
The authoritative list is one command away:
Output control¶
| Key | Meaning |
|---|---|
DEVICE / --device |
cpu, cuda or cuda:N; the requested device is recorded separately from the one actually used |
OUTPUT_DIR / --output |
the run directory |
WRITE_OUTCAR, WRITE_XDATCAR, WRITE_TRAJECTORY |
which files are written |
WRITE_FORCES, WRITE_STRESS |
which arrays and columns are written |
NEB refuses to switch off its mandatory outputs, rather than hand you a result that quietly lacks them.
Environment variables¶
| Variable | Effect |
|---|---|
MLIPORT_SETTINGS |
explicit settings.ini path |
MLIPORT_ROOT |
mliport checkout root; where a bare MODEL_PATH file name is looked up in models/ |
MLIPORT_JOBS_DIR |
queue and job registry directory |
MLIPORT_CANCEL_GRACE_SECONDS |
grace period when cancelling a job |
MLIPORT_LEASED_GPU_UUID |
the single GPU leased to a queue worker |
CUDA_VISIBLE_DEVICES |
device visibility; the queue sets it when it leases a GPU, so do not override it inside a running job |
The TUI¶
mliport tui opens on a new-task wizard, because that is the common case: pick a
calculation type, a structure file and a model - the backend first, then a file
from models/ - and it writes a task folder with INCAR.mliport and a
byte-for-byte copy of the structure, then prints cd <folder> && mliport run.
"Create & Run" executes mliport run itself, not a second run path. The wizard
leaves TASK (and HEAD for a multi-branch checkpoint) as REQUIRED
placeholders: the UMA task family and the other backends' bulk/molecule
semantic are model decisions, so it says what is still to fill in instead of
running with a template default.
Everything else stays available under "Advanced": the manual configuration
screens for SP, OPT, MD, NEB and CONFSEARCH, the template generator (which uses
the same generator as mliport template), background jobs and analysis. They
expose the same configuration, including an explicit backend choice, and will
not start a run until a backend and a model are chosen. They submit through the
same queue helper as the CLI, so the two cannot drift apart. The analysis screen
offers every analyze task with the common options; the less common ones (for
example GEMDAT site discovery) are command-line only.