Modeling and Simulation

Modeling and simulation are at the heart of SAMSON, and the SDK reflects that by separating scientific responsibilities into a few explicit abstractions.

This page answers a practical developer question: what kind of model or simulator should my feature be?

The two main library groups involved are the Modeling Library Group and the Simulation Library Group.

SAMSON represents nanosystems using five categories of models:

• Structural models describe geometry and topology
• Visual models provide graphical representations
• Dynamical models describe dynamical degrees of freedom
• Interaction models describe energies and forces
• Property models describe properties that do not fit the first four categories

Simulators and state updaters then operate on those models to advance a system through time or iterations.

Models and simulators are nodes in the data graph. All models derive from SBMModel, model nodes derive from SBMModelNode, and simulators derive from SBSSimulator.

A quick mental model

If you are choosing where your code belongs:

• use a structural model for what the system is
• use a visual model for how it looks
• use a dynamical model for what can move
• use an interaction model for what exerts forces or contributes energy
• use a property model for extra scientific data
• use a state updater for the numerical rule that advances state
• use a simulator for the runtime object that coordinates a dynamical model, interaction model, and state updater

Models

Structural models

Structural models describe the geometry and topology of nanosystems.

Typical contents include atoms (SBAtom), bonds (SBBond), and higher-level structural organization such as molecules (SBMolecule) and residues (SBResidue).

Use a structural model when your extension defines what exists in the system and how those parts are connected.

Structural models may send structural events.

Visual models

Visual models provide graphical representations.

Examples include secondary-structure representations, isosurfaces, field visualizations, and custom rendering styles.

Use a visual model when the main responsibility is how something is shown, not what it physically is.

SAMSON Extensions provide visual models by deriving from SBMVisualModel and implementing display functions called by the renderer. Visual models may send visual events.

Dynamical models

Dynamical models describe where the degrees of freedom are and what the dynamic state is.

For example, a particle system applied to structural particles assigns translational degrees of freedom and stores dynamic quantities such as positions, momenta, and masses.

Use a dynamical model when your extension needs a formal state that can evolve during simulation.

Dynamical models support passive signaling mechanisms through buffers (i.e. they provide a list of updated positions and updated momenta at each time step), and may send dynamical events.

Interaction models

Interaction models represent energies and forces.

Examples include Lennard-Jones interactions, spring models, elastic network models, and force fields.

An interaction model provides force and energy information corresponding to the degrees of freedom of a dynamical model. For example, applied to a particle system, it provides both total energy and particle forces.

Use an interaction model when the feature computes physical interactions rather than only representing state or appearance.

SAMSON Extensions provide interaction models by deriving from SBMInteractionModel and implementing functions such as SBMInteractionModel::updateInteractions.

Interaction models support passive signaling mechanisms through buffers (i.e. they provide a list of updated forces at each time step), and may send interaction events.

Property models

Property models represent scientific properties that are not already covered by the other four model categories.

Examples include a scalar such as gyration radius, a scalar or vector field, or a function object with evaluable values.

Use a property model when you need to attach computed or derived scientific information to a system without forcing it into structural, visual, dynamical, or interaction semantics.

SAMSON Extensions provide property models by deriving from SBMPropertyModel. Specific subfamilies may expose additional functions, such as SBMPropertyModelFunction::getValue for function-valued models.

Property models may send property events.

State updaters

State updaters implement the numerical rule used to advance state during simulation.

Examples include minimization algorithms, Monte Carlo updates, and molecular dynamics integration steps.

SAMSON Extensions provide state updaters by deriving from SBSStateUpdater and implementing functions such as SBSStateUpdater::updateState.

Simulators

Simulators derive from SBSSimulator and coordinate runtime evolution.

A simulator typically connects:

• a dynamical model
• an interaction model
• a state updater

When interactive simulation starts, SAMSON steps through simulators in the data graph and lets them update the attached dynamical state.

Use a simulator when your extension needs a runtime object that orchestrates the simulation process, not just one scientific ingredient of it.

Simulators may send simulator events, while state updaters may send state updater events.

Tip

See User guide: Modeling and Simulation for more information on how simulators are used in SAMSON.