Simulator API

MoltenSaltSimulator

Class for building molten salt systems and running molecular dynamics simulations supported by energy estimates from uMLIPs.

__init__

__init__(
    model_name: str | None = None,
    model_parameters: dict | None = None,
    device: str = "cuda",
    dispersion: str | None = "DFTD3",
    dispersion_functional: str = "pbe",
    dispersion_cutoff: float = 21.0,
    dispersion_damping: str = "bj",
)

Initialize the simulator with a specific ML potential.

Parameters:

Name	Type	Description	Default
model_name	str | None	Which MLIP to use. If not set, no calculator will be set. Defaults to None.	None
model_parameters	dict | None	Parameters for the MLIP. Defaults to None.	None
device	str	Which device to use for the calculations, select from "cpu" and "cuda". Defaults to "cuda".	'cuda'
dispersion	str | None	Which dispersion calculator to use for long ranger interactions, select from "DFTD2", "DFTD3", "DFTD4" or None. Defaults to "DFTD3".	'DFTD3'
dispersion_functional	str	Functional for the dispersion, should match the functional used in the MLIP calculator. Defaults to "pbe".	'pbe'
dispersion_cutoff	float	Cutoff distance for the dispersion calculator in Å. Only applies if dispersion is "DFTD2" or "DFTD3". Defaults to 21.0.	21.0
dispersion_damping	str	Damping function for the dispersion calculator. Only applies if dispersion is "DFTD2" or "DFTD3". Defaults to "bj".	'bj'

Raises:

Type	Description
ValueError	If the specified dispersion calculator is not supported.

create_simulation_folder

create_simulation_folder(
    base_name: Path | str = "simulation",
) -> tuple[str, str]

Create a folder structure for simulation outputs.

Parameters:

Name	Type	Description	Default
base_name	Path | str	Name of the base folder to be created in the current working directory. Defaults to "simulation".	'simulation'

Returns:

Type	Description
tuple[str, str]	Tuple[str, str]: Tuple of the folders where the NPT and NVT trajectories will be stored.

build_system

build_system(
    salt_anion: list[str],
    salt_cation: list[str],
    n_anions: list[int],
    n_cations: list[int],
    density_guess: float,
    lattice: str = "random",
    random_removal: bool = False,
    random_min_distance: float = 1.6,
    random_max_attempts: int = 100000,
) -> Atoms

Build a molten salt system with random or rocksalt initial positions.

Parameters:

Name	Type	Description	Default
salt_anion	list[str]	Chemical symbols for anions	required
salt_cation	list[str]	Chemical symbols for cations	required
n_anions	list[int]	Number of atoms for each anion type	required
n_cations	list[int]	Number of atoms for each cation type	required
density_guess	float	Initial density guess in g/cm³	required
lattice	str	Initial lattice type ("random" or "rocksalt"). Defaults to "random".	'random'
random_removal	bool	If True and lattice is "rocksalt", randomly remove excess atoms to match the desired composition. If False, simply take the first N positions from the generated lattice. Defaults to False.	False
random_min_distance	float	Minimum distance between atoms in the random lattice in Å. Defaults to 1.6.	1.6
random_max_attempts	int	Maximum number of attempts to place atoms at random positions. Defaults to 100000.	100000

Raises:

Type	Description
ValueError	If the number of distinct ions and the number of amounts of those ions do not match.
ValueError	If the lattice type is not supported.
RuntimeError	If the initial box size is too small for the requested lattice (100'000 attempts were not enough to place an atom at a random position with a distance of 1.6 Å to every other atom).

Returns:

Name	Type	Description
Atoms	Atoms	The constructed system

run_npt_simulation

run_npt_simulation(
    atoms: Atoms,
    T: float | int,
    npt_dyn: str = "nptberendsen",
    steps: int = 1000,
    timestep_fs: float = 1.0,
    taut_fs: float = 100.0,
    taup_fs: float = 1000.0,
    compressibility_per_bar: float = 5e-06,
    pressure_bar: float = 1.01325,
    tchain: int = 3,
    pchain: int = 3,
    tloop: int = 1,
    ploop: int = 1,
    print_interval: int = 100,
    write_interval: int = 10,
    traj_file: str | Path = "npt_simulation.traj",
    print_status: bool = True,
    logfile: str | Path | None = "npt_run.log",
) -> Atoms

Run NPT (constant particles, pressure, temperature) molecular dynamics simulation.

Parameters:

Name	Type	Description	Default
atoms	Atoms	System to simulate.	required
T	float | int	Temperature in K.	required
npt_dyn	str	NPT dynamics to use. Defaults to "nptberendsen". Choices: "nptberendsen", "mtknpt", "melchionna". Defaults to "nptberendsen".	'nptberendsen'
steps	int	Number of MD steps. Defaults to 1000.	1000
timestep_fs	float	Time step dt for the simulation in fs. Defaults to 1.0.	1.0
taut_fs	float	Time constant for the NPT temperature coupling in fs. Defaults to 100.0.	100.0
taup_fs	float	Time constant for the NPT pressure coupling in fs. Defaults to 1000.0.	1000.0
compressibility_per_bar	float	Compressibility of the system per bar in 1/bar. Defaults to 5e-6.	5e-06
pressure_bar	float	Pressure in bar. Defaults to 1.01325.	1.01325
tchain	int	The number of thermostat variables in the Nose-Hoover thermostat. Only applies if npt_din is "mtknpt". Defaults to 3.	3
pchain	int	The number of barostat variables in the MTK barostat. Only applies if npt_din is "mtknpt". Defaults to 3.	3
tloop	int	The number of sub-steps in thermostat integration. Only applies if npt_din is "mtknpt". Defaults to 1.	1
ploop	int	The number of sub-steps in barostat integration. Only applies if npt_din is "mtknpt". Defaults to 1.	1
print_interval	int	Interval for printing status. Defaults to 100.	100
write_interval	int	Interval for writing trajectory frames. Defaults to 10.	10
traj_file	str | Path	Output trajectory file path. Defaults to "npt_simulation.traj".	'npt_simulation.traj'
print_status	bool	Whether to print simulation status. Defaults to True.	True
logfile	str | Path | None	Logfile for the NPT dynamics simulation, "-" for stdout, None for no logfile. Defaults to "npt_run.log".	'npt_run.log'

Returns:

Name	Type	Description
Atoms	Atoms	ASE atoms object of the equilibrated system

run_nvt_simulation

run_nvt_simulation(
    atoms: Atoms,
    T: float | int,
    nvt_dyn: str = "nosehoover",
    steps: int = 1000,
    timestep_fs: float = 1.0,
    tdamp_fs: float = 100.0,
    print_interval: int = 100,
    write_interval: int = 10,
    traj_file: str | Path = "nvt_simulation.traj",
    print_status: bool = True,
    logfile: str | Path | None = "nvt_run.log",
)

Run NVT (constant particles, volume, temperature) molecular dynamics simulation.

Parameters:

Name	Type	Description	Default
atoms	Atoms	System to simulate.	required
T	float | int	Temperature in K.	required
nvt_dyn	str	NVT dynamics to use. Choices: "nvtberendsen", "nosehoover", "langevin", "bussi", "andersen". Defaults to "nosehoover".	'nosehoover'
steps	int	Number of MD steps. Defaults to 1000.	1000
timestep_fs	float	Time step dt for the simulation in fs. Defaults to 1.0.	1.0
tdamp_fs	float	Characteristic time scale for thermostat in fs, typically 100*timestep_fs. Defaults to 100.0.	100.0
print_interval	int	Interval for printing status. Defaults to 100.	100
write_interval	int	Interval for writing trajectory frames. Defaults to 10.	10
traj_file	str | Path	Output trajectory file path. Defaults to "nvt_simulation.traj".	'nvt_simulation.traj'
print_status	bool	Whether to print simulation status. Defaults to True.	True
logfile	str | Path | None	Logfile for the NoseHooverChainNVT dynamics simulation, "-" for stdout, None for no logfile. Defaults to "nvt_run.log".	'nvt_run.log'