Advanced numerical modules

The numerical modules operate on normalized float64 arrays. They are useful for diagnostics, custom integrations, and understanding the implementation; ordinary callers should start with the quantity-bearing API.

Normalized state

class vcsmd.models.SimulationState(cell: NDArray[numpy.float64], fractional_positions: NDArray[numpy.float64], fractional_velocities: NDArray[numpy.float64], cell_velocity: NDArray[numpy.float64], fractional_acceleration: NDArray[numpy.float64], previous_fractional_acceleration: NDArray[numpy.float64], cell_acceleration: NDArray[numpy.float64], previous_cell_acceleration: NDArray[numpy.float64], reference_cell: NDArray[numpy.float64], step_index: int = 0, time: float = 0.0, averages: vcsmd.models.RunningAverages = <factory>, rescalings_remaining: int = 0)

Bases: object

Parameters:

  • cell (NDArray[float64])

  • fractional_positions (NDArray[float64])

  • fractional_velocities (NDArray[float64])

  • cell_velocity (NDArray[float64])

  • fractional_acceleration (NDArray[float64])

  • previous_fractional_acceleration (NDArray[float64])

  • cell_acceleration (NDArray[float64])

  • previous_cell_acceleration (NDArray[float64])

  • reference_cell (NDArray[float64])

  • step_index (int)

  • time (float)

  • averages (RunningAverages)

  • rescalings_remaining (int)

cell: NDArray[float64]
fractional_positions: NDArray[float64]
fractional_velocities: NDArray[float64]
cell_velocity: NDArray[float64]
fractional_acceleration: NDArray[float64]
previous_fractional_acceleration: NDArray[float64]
cell_acceleration: NDArray[float64]
previous_cell_acceleration: NDArray[float64]
reference_cell: NDArray[float64]
step_index: int = 0
time: float = 0.0
averages: RunningAverages
rescalings_remaining: int = 0
class vcsmd.models.RunningAverages(count: int = 0, potential_sum: float = 0.0, kinetic_sum: float = 0.0, pressure_sum: float = 0.0)

Bases: object

Parameters:

  • count (int)

  • potential_sum (float)

  • kinetic_sum (float)

  • pressure_sum (float)

count: int = 0
potential_sum: float = 0.0
kinetic_sum: float = 0.0
pressure_sum: float = 0.0
class vcsmd.models.Observables(step_index, time, atomic_potential_energy, atomic_kinetic_energy, cell_kinetic_energy, external_pressure_energy, total_energy, pressure, volume, atomic_temperature, extended_temperature, running_extended_temperature, average_potential_energy, average_kinetic_energy, average_pressure)

Bases: object

Internal-unit measurements at a completed step, before control events.

Use vcsmd.with_units to obtain their unit-bearing public representation.

Parameters:

  • step_index (int)

  • time (float)

  • atomic_potential_energy (float)

  • atomic_kinetic_energy (float)

  • cell_kinetic_energy (float)

  • external_pressure_energy (float)

  • total_energy (float)

  • pressure (float)

  • volume (float)

  • atomic_temperature (float)

  • extended_temperature (float)

  • running_extended_temperature (float)

  • average_potential_energy (float)

  • average_kinetic_energy (float)

  • average_pressure (float)

step_index: int
time: float
atomic_potential_energy: float
atomic_kinetic_energy: float
cell_kinetic_energy: float
external_pressure_energy: float
total_energy: float
pressure: float
volume: float
atomic_temperature: float
extended_temperature: float
running_extended_temperature: float
average_potential_energy: float
average_kinetic_energy: float
average_pressure: float
class vcsmd.models.SimulationEvent(kind: vcsmd.models.EventKind, step_index: int, scale: float | None = None, particle_components: int = 0, cell_components: int = 0)

Bases: object

Parameters:

  • kind (EventKind)

  • step_index (int)

  • scale (float | None)

  • particle_components (int)

  • cell_components (int)

kind: EventKind
step_index: int
scale: float | None = None
particle_components: int = 0
cell_components: int = 0
class vcsmd.models.StepResult(state: vcsmd.models.SimulationState, observables: vcsmd.models.Observables, events: tuple[vcsmd.models.SimulationEvent, ...] = ())

Bases: object

Parameters:
state: SimulationState
observables: Observables
events: tuple[SimulationEvent, ...] = ()

Geometry

Cell matrices store cell vectors as columns. Fractional particle arrays use one particle per row, and Cartesian positions are fractional_positions @ cell.T.

class vcsmd.geometry.CellGeometry(volume, metric, inverse_metric, cofactor)

Bases: object

Cached geometric tensors for a periodic cell.

metric is cell.T @ cell and cofactor is the matrix satisfying cell.T @ cofactor = volume * I (equivalently volume * inv(cell).T). All array fields are independent read-only arrays.

Parameters:

  • volume (float)

  • metric (ndarray)

  • inverse_metric (ndarray)

  • cofactor (ndarray)

vcsmd.geometry.cell_geometry(cell)

Return volume, metric, inverse metric, and cofactor for cell.

The cell vectors are columns. Inputs are copied and never modified.

Parameters:

cell (ndarray)

Return type:

CellGeometry

vcsmd.geometry.cell_parameters(cell)

Return vector lengths and (alpha, beta, gamma) angles in degrees.

The angles are respectively between (b, c), (c, a), and (a, b).

Parameters:

cell (ndarray)

Return type:

tuple[ndarray, ndarray]

vcsmd.geometry.replicate_cell(cell, fractional_positions, repeats)

Replicate a cell and its basis in lexicographic shift order.

For every shift (i, j, k) with i, then j, then k varying fastest in the nested loops, all original atoms are emitted in their input order. The returned index map gives each emitted atom’s source basis index.

Parameters:

  • cell (ndarray)

  • fractional_positions (ndarray)

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

Return type:

tuple[ndarray, ndarray, ndarray]

vcsmd.geometry.validate_image_range(cell, cutoff, image_range)

Ensure the requested image range reaches at least the cutoff radius.

The required perpendicular face height for direction i is volume / area(face_i). Thus n_i images in that direction cover a distance n_i * height_i. This check prevents silently truncating a periodic sum.

Parameters:

  • cell (ndarray)

  • cutoff (float)

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

Return type:

None

Normalized dynamics

These functions operate on vcsmd.models.NumericalModel and normalized states. They are the advanced counterpart of the quantity-bearing functions in the public API.

vcsmd.dynamics.initialize(model, initial_conditions, *, seed)

Create a deterministic state without consuming external random state.

The previous acceleration is initialized to the current acceleration. This supplies a second-order self-start instead of inventing zero past forces. Provided velocities must respect the removed center-of-mass constraint.

Parameters:
Return type:

SimulationState

vcsmd.dynamics.step(model, state)

Advance once, returning new arrays and pre-control observables.

The one-pass velocity-dependent predictor/corrector matches the source’s method. Stored accelerations are those evaluated at predicted velocities.

Parameters:
Return type:

StepResult

vcsmd.dynamics.simulate(model, initial_state, *, steps)
Parameters:
Return type:

Iterator[StepResult]

Lennard–Jones evaluation

class vcsmd.potentials.ForceResult(potential_energy, forces, virial)

Bases: object

Lennard–Jones energy, Cartesian forces, and configurational virial.

Parameters:

  • potential_energy (float)

  • forces (ndarray)

  • virial (ndarray)

vcsmd.potentials.evaluate_lennard_jones(cell, fractional_positions, *, sigma, epsilon, cutoff, image_range, batch_size=65536)

Evaluate an unshifted, inclusive-cutoff Lennard–Jones potential.

The central cell’s distinct pairs are counted once. Every nonzero image shift is evaluated for all ordered particle pairs; those terms receive a half weight for energy and virial, while each central particle receives the full force from every image. This retains self-image interactions and gives the periodic force and virial their usual translationally invariant values without constructing an all-pairs/all-images tensor.

Parameters:

  • cell (ndarray)

  • fractional_positions (ndarray)

  • sigma (float)

  • epsilon (float)

  • cutoff (float)

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

  • batch_size (int)

Return type:

ForceResult

The evaluator uses an unshifted, inclusive cutoff and returns potential energy, Cartesian forces, and configurational virial. All particles share the global parameter pair from the normalized model.

Unit constants

vcsmd.units.ureg

The unit registry stores the definitions and relationships between units.

Parameters

filename :

path of the units definition file to load or line-iterable object. Empty string to load the default definition file. (default) None to leave the UnitRegistry empty.

force_ndarraybool

convert any input, scalar or not to a numpy.ndarray. (Default: False)

force_ndarray_likebool

convert all inputs other than duck arrays to a numpy.ndarray. (Default: False)

default_as_delta :

In the context of a multiplication of units, interpret non-multiplicative units as their delta counterparts. (Default: False)

autoconvert_offset_to_baseunit :

If True converts offset units in quantities are converted to their plain units in multiplicative context. If False no conversion happens. (Default: False)

on_redefinitionstr

action to take in case a unit is redefined. ‘warn’, ‘raise’, ‘ignore’ (Default: ‘raise’)

auto_reduce_dimensions :

If True, reduce dimensionality on appropriate operations. (Default: False)

autoconvert_to_preferred :

If True, converts preferred units on appropriate operations. (Default: False)

preprocessors :

list of callables which are iteratively ran on any input expression or unit string or None for no preprocessor. (Default=None)

fmt_locale :

locale identifier string, used in format_babel or None. (Default=None)

case_sensitivebool, optional

Control default case sensitivity of unit parsing. (Default: True)

cache_folderstr or pathlib.Path or None, optional

Specify the folder in which cache files are saved and loaded from. If None, the cache is disabled. (default)

Parameters:

  • input_string (str)

  • case_sensitive (bool | None)

  • values (QuantityArgument)

Return type:

QuantityT

vcsmd.units.Quantity
Parameters:

units (UnitLike | None)

Return type:

PlainQuantity

The normalized solver uses bohr, Rydberg, rydberg_time, and the corresponding mass units. Unit conversion at the application boundary is handled by vcsmd.config and vcsmd.simulation.