Public simulation API

The user-facing result and evolution types are implemented in vcsmd.simulation and re-exported by vcsmd. vcsmd.SimulationState, vcsmd.Observables, and vcsmd.StepResult are the quantity-bearing classes; the similarly named classes in vcsmd.models are normalized numerical types.

State and results

class vcsmd.SimulationState(numerical)

Bases: object

A read-only state with dimensional fields exposed as Pint quantities.

numerical is an explicit escape hatch for advanced numerical work and native persistence. Its arrays are independently owned and read-only.

Parameters:

numerical (SimulationState)

numerical: SimulationState
property cell: Quantity
property fractional_positions: ndarray
property fractional_velocities: Quantity
property positions: Quantity
property peculiar_velocities: Quantity
property cartesian_velocities: Quantity

Full instantaneous Cartesian derivative, including cell deformation.

property cell_velocity: Quantity
property fractional_acceleration: Quantity
property cell_acceleration: Quantity
property reference_cell: Quantity
property step_index: int
property time: Quantity
class vcsmd.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

Measurements for one completed step, before rescaling or quenching.

Dimensional values are Pint quantities. Atomic temperature uses particle kinetic energy; extended temperature also includes cell kinetic energy. The running extended temperature is the quantity used by the controller.

Parameters:

  • step_index (int)

  • time (Quantity)

  • atomic_potential_energy (Quantity)

  • atomic_kinetic_energy (Quantity)

  • cell_kinetic_energy (Quantity)

  • external_pressure_energy (Quantity)

  • total_energy (Quantity)

  • pressure (Quantity)

  • volume (Quantity)

  • atomic_temperature (Quantity)

  • extended_temperature (Quantity)

  • running_extended_temperature (Quantity)

  • average_potential_energy (Quantity)

  • average_kinetic_energy (Quantity)

  • average_pressure (Quantity)

step_index: int
time: Quantity
atomic_potential_energy: Quantity
atomic_kinetic_energy: Quantity
cell_kinetic_energy: Quantity
external_pressure_energy: Quantity
total_energy: Quantity
pressure: Quantity
volume: Quantity
atomic_temperature: Quantity
extended_temperature: Quantity
running_extended_temperature: Quantity
average_potential_energy: Quantity
average_kinetic_energy: Quantity
average_pressure: Quantity
class vcsmd.StepResult(state, observables, events=())

Bases: object

An independently owned next state, measurements, and controller events.

observables precede controller actions within the step. state is after those actions and is the state to pass to the next step or save. Events describe actions for the caller to report; no logging occurs here.

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

StepResult.observables describes the completed step before temperature rescaling or minimization quenching. StepResult.state is the state after those actions and is the state to pass to the next step or save.

Evolution functions

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

Create the public state from the two objects returned by prepare.

seed is explicit and affects only a local random generator. Thermal initialization removes global center-of-mass momentum; provided velocities must already satisfy that constraint. The returned state includes Beeman history, exposes physical quantities, and owns read-only numerical arrays. No input arrays are modified and no files are accessed.

Parameters:
Return type:

SimulationState

vcsmd.step(model, state)

Advance one Beeman step without changing model or state.

Pass a state returned by this public API or vcsmd.load_checkpoint. The result includes dimensional observables and any rescaling or quenching events. Its next state can be passed back to this function unchanged.

Parameters:
Return type:

StepResult

vcsmd.simulate(model, initial_state, *, steps)

Yield exactly steps successive results from the supplied state.

steps is a nonnegative count of additional steps. Results are generated lazily, so the caller controls iteration and need not retain a trajectory in memory. Each result owns its numerical state; retaining a result does not cause later steps to modify it. This function performs no file I/O.

Parameters:
Return type:

Iterator[StepResult]

vcsmd.with_units(observables)

Attach physical units to normalized measurements without changing them.

Parameters:

observables (Observables)

Return type:

Observables

For interactive use, from vcsmd import * is supported and follows vcsmd.__all__; explicit imports remain preferable in maintained code. Configuration loading/saving, checkpoints, and application execution are also exported from the package root. Their signatures are documented on the native I/O and execution pages.