Configuration and normalized models

vcsmd.config contains the unit-aware domain objects used to construct a simulation. prepare converts them into immutable normalized objects for the solver. Native JSON, YAML, and TOML files are parsed into these same objects by the functions in the I/O reference.

Unit-aware configuration

class vcsmd.Structure(cell, fractional_positions, masses, species)

Bases: object

Cell columns and fractional particle positions; masses are per particle.

Parameters:

  • cell (Quantity)

  • fractional_positions (ndarray)

  • masses (Quantity)

  • species (tuple[str, ...])

cell: Quantity
fractional_positions: ndarray
masses: Quantity
species: tuple[str, ...]
class vcsmd.LennardJones(sigma=<factory>, epsilon=<factory>)

Bases: object

One global Lennard–Jones interaction with dimensional sigma and epsilon.

All particles share these parameters; species labels do not select separate interactions. Use original_argon() for the source’s numeric preset.

Parameters:

  • sigma (Quantity)

  • epsilon (Quantity)

sigma: Quantity
epsilon: Quantity
classmethod original_argon()

The numerical parameter choices of the original active force model.

Return type:

LennardJones

All particles use one global Lennard–Jones parameter pair; species labels do not select separate interactions or mixing rules.

class vcsmd.SimulationConfig(structure, mode, timestep, steps, cutoff, image_range, temperature=<factory>, external_pressure=<factory>, cell_inertia=None, potential=<factory>, temperature_control=<factory>, initialization=InitializationMode.THERMAL, fractional_velocities=None, cell_velocity=None, seed=119, output_interval=1, title='VCSMD simulation')

Bases: object

User-facing inputs for a complete run, independent of file format.

Dimensional fields are Pint quantities and categorical fields are enums. prepare validates and normalizes these inputs into a NumericalModel and InitialConditions. Step count, output cadence, title, and seed are application settings; they are not hidden mutable state of the solver.

Parameters:

  • structure (Structure)

  • mode (SimulationMode)

  • timestep (Quantity)

  • steps (int)

  • cutoff (Quantity)

  • image_range (tuple[int, int, int])

  • temperature (Quantity)

  • external_pressure (Quantity)

  • cell_inertia (Quantity | None)

  • potential (LennardJones)

  • temperature_control (TemperatureControl)

  • initialization (InitializationMode)

  • fractional_velocities (Quantity | None)

  • cell_velocity (Quantity | None)

  • seed (int)

  • output_interval (int)

  • title (str)

structure: Structure
mode: SimulationMode
timestep: Quantity
steps: int
cutoff: Quantity
image_range: tuple[int, int, int]
temperature: Quantity
external_pressure: Quantity
cell_inertia: Quantity | None = None
potential: LennardJones
temperature_control: TemperatureControl
initialization: InitializationMode = 'thermal'
fractional_velocities: Quantity | None = None
cell_velocity: Quantity | None = None
seed: int = 119
output_interval: int = 1
title: str = 'VCSMD simulation'
vcsmd.prepare(config)

Normalize quantities into an explicit immutable numerical model and state input.

Parameters:

config (SimulationConfig)

Return type:

tuple[NumericalModel, InitialConditions]

Enums and controller settings

These definitions are also re-exported from vcsmd:

class vcsmd.SimulationMode(*values)

Bases: Enum

FIXED_DYNAMICS = 'fixed-dyn'
FIXED_MINIMIZATION = 'fixed-min'
CELL_DYNAMICS = 'cell-dyn'
CELL_MINIMIZATION = 'cell-min'
METRIC_DYNAMICS = 'metric-dyn'
METRIC_MINIMIZATION = 'metric-min'
STRAIN_DYNAMICS = 'strain-dyn'
STRAIN_MINIMIZATION = 'strain-min'
property variable_cell: bool
property minimizes: bool
property metric_cell: bool
property strain_cell: bool
class vcsmd.InitializationMode(*values)

Bases: Enum

THERMAL = 'thermal'
PROVIDED = 'provided'
class vcsmd.EventKind(*values)

Bases: Enum

TEMPERATURE_RESCALED = 'temperature-rescaled'
VELOCITIES_QUENCHED = 'velocities-quenched'
class vcsmd.TemperatureControl(interval: int = 100, max_rescales: int = 0, relative_tolerance: float = 0.01)

Bases: object

Parameters:

  • interval (int)

  • max_rescales (int)

  • relative_tolerance (float)

interval: int = 100
max_rescales: int = 0
relative_tolerance: float = 0.01

Variable-cell modes require cell_inertia. Ordinary cell modes use mass units; modified-metric and reference-strain modes use mass/length⁴. Provided particle velocities must satisfy the zero mass-weighted center-of-mass constraint.

Normalized model inputs

These immutable types are the advanced numerical boundary returned by prepare. Their arrays use internal units and are read-only.

class vcsmd.NumericalModel(mode: vcsmd.models.SimulationMode, masses: NDArray[numpy.float64], species: tuple[str, ...], timestep: float, cutoff: float, image_range: tuple[int, int, int], sigma: float, epsilon: float, external_pressure: float, cell_inertia: float, temperature: float, boltzmann_constant: float, temperature_control: vcsmd.models.TemperatureControl = <factory>)

Bases: object

Parameters:

  • mode (SimulationMode)

  • masses (NDArray[float64])

  • species (tuple[str, ...])

  • timestep (float)

  • cutoff (float)

  • image_range (tuple[int, int, int])

  • sigma (float)

  • epsilon (float)

  • external_pressure (float)

  • cell_inertia (float)

  • temperature (float)

  • boltzmann_constant (float)

  • temperature_control (TemperatureControl)

mode: SimulationMode
masses: NDArray[float64]
species: tuple[str, ...]
timestep: float
cutoff: float
image_range: tuple[int, int, int]
sigma: float
epsilon: float
external_pressure: float
cell_inertia: float
temperature: float
boltzmann_constant: float
temperature_control: TemperatureControl
class vcsmd.InitialConditions(cell: NDArray[numpy.float64], fractional_positions: NDArray[numpy.float64], mode: vcsmd.models.InitializationMode = <InitializationMode.THERMAL: 'thermal'>, fractional_velocities: NDArray[numpy.float64] | None = None, cell_velocity: NDArray[numpy.float64] | None = None)

Bases: object

Parameters:

  • cell (NDArray[float64])

  • fractional_positions (NDArray[float64])

  • mode (InitializationMode)

  • fractional_velocities (NDArray[float64] | None)

  • cell_velocity (NDArray[float64] | None)

cell: NDArray[float64]
fractional_positions: NDArray[float64]
mode: InitializationMode = 'thermal'
fractional_velocities: NDArray[float64] | None = None
cell_velocity: NDArray[float64] | None = None