Skip to content

Config

Layered configuration for the engines and wrappers, built on molcfg.

Quick reference

Symbol Summary Preferred for
load_config Merge the four layers (defaults → user → project → run), validate, freeze Getting the config an engine or wrapper runs with
tool_settings One tool's resolved settings, each with the layer and key it came from Inspecting what a tool will run
ToolSettings executable, env, env_manager, conda_executable, launcher, env_vars, timeout, sources Reading resolved settings
user_config_path ~/.molcrafts/molpy/config/config.toml (MOLCRAFTS_HOME moves it) Finding the user layer's file
PROJECT_CONFIG_NAME molpy.toml, the project layer's file name Finding the project layer's file
LAYERS ("defaults", "user", "project", "run") Naming a layer
DEFAULTS The package defaults (the defaults layer) Seeing what an unset key means

Canonical example

from molpy.config import load_config, tool_settings

config = load_config({"engine": {"lammps": {"launcher": ["srun", "-n", "4"]}}})
settings = tool_settings(config, "engine.lammps")
print(settings.launcher)  # ('srun', '-n', '4')
print(settings.sources["launcher"])  # ('run', 'engine.lammps.launcher')
print(settings.sources["env"])  # ('defaults', 'engine.env') unless a file sets it

Key behavior

  • Tables: [conda] (executable), [engine] and [engine.<name>] for lammps, gromacs, openmm, cp2k; [wrapper] and [wrapper.<name>] for antechamber, tleap, parmchk2, prepgen, sander
  • Keys: executable, env, env_manager ("conda" / "venv"), env_vars, timeout (seconds) and, for engines, launcher; a group table holds what its tools share, a tool's own key replaces the group's
  • Later layers win key by key; tables such as env_vars merge across layers, lists such as launcher are replaced
  • An unknown key or a wrong type is refused when the config loads, naming the key and the files read; the loaded config is frozen
  • Loading and resolving log to molpy.config (DEBUG)

Full API

load_config 

load_config(
    overrides=None, *, project_dir=None, environ=None
)

Resolve molpy's configuration through its four layers.

Later layers win key by key (molcfg's deep merge): defaults, then user (:func:user_config_path, when the file exists), then project (molpy.toml in project_dir, when it exists), then run (overrides). The merged result is validated against the schema in this module's docstring and frozen.

Parameters:

Name Type Description Default
overrides Mapping[str, Any] | None

The run layer: nested tables shaped like the files, e.g. {"engine": {"lammps": {"launcher": ["srun"]}}}.

 None
project_dir str | Path | None

Where molpy.toml is looked up; the working directory when None.

 None
environ Mapping[str, str] | None

The environment the user config directory is resolved in; None is the process environment.

 None

Returns:

Type Description
Config

The frozen :class:molcfg.Config; config.meta(path)["source"]
Config

names the layer a value came from.

Raises:

Type Description
ValidationError

A layer sets an unknown key or a value of the wrong type. The message names the offending keys.

tool_settings 

tool_settings(config, tool)

Resolve the settings of tool ("engine.lammps", "wrapper.tleap").

Each setting is the tool's own key when a layer set it, else its group's (engine.<key> / wrapper.<key>); :attr:ToolSettings.sources records which, and from which layer.

Parameters:

Name Type Description Default
config Config

A config from :func:load_config.

 required
tool str

"<group>.<name>" with group engine (lammps, gromacs, openmm, cp2k) or wrapper (antechamber, tleap, parmchk2, prepgen, sander).

 required

Raises:

Type Description
KeyError

tool is not a known engine or wrapper.
ValueError

A timeout is not positive.

ToolSettings dataclass 

ToolSettings(
    tool,
    executable,
    env,
    env_manager,
    conda_executable,
    launcher=(),
    env_vars=dict(),
    timeout=None,
    sources=dict(),
)

What one engine or wrapper runs with, resolved from a config.

Attributes:

Name Type Description
tool str

The tool's table, "<group>.<name>" ("engine.lammps").
executable str | None

The program to run (a name looked up in the environment, or a path); None lets the tool choose.
env str | None

Conda env name / prefix, or venv prefix; None is the system environment.
env_manager Literal['conda', 'venv'] | None

"conda" or "venv", together with env.
conda_executable str

The conda that conda run invokes.
launcher tuple[str, ...]

MPI / scheduler prefix before the executable (engines only; empty for wrappers).
env_vars Mapping[str, str]

Environment variables set for the subprocess.
timeout float | None

Seconds before the subprocess is killed; None is no limit.
sources Mapping[str, tuple[str, str]]

Setting name → (layer, path): the layer (:data:LAYERS) and the dotted config key the value was read from — the tool's own key, or its group's when the tool's table leaves the key unset.

user_config_path 

user_config_path(environ=None)

The user layer's file: ~/.molcrafts/molpy/config/config.toml.

The directory is :func:molcfg.project_config_dir ("molpy"), which honours MOLCRAFTS_HOME and creates the directory; the file itself may not exist.

Parameters:

Name Type Description Default
environ Mapping[str, str] | None

The environment to resolve MOLCRAFTS_HOME / HOME in; None is the process environment.

 None