Ensembles

Ensembles

This module provides the main function run_dynamics. This serves to run multiple trajectories for a given simulation type, sampling from an initial distribution.

EnsembleSaver{F<:Tuple}

Store a tuple of functions with the signature f(sol) where sol is a DiffEq solution object. EnsembleSaver will evaluate each of these functions and return the result in a Dictionary.

Average the outputs over all trajectories.

Select the initial conditions from the distribution in order.

Obtain initial conditions by randomly sampling the distribution.

Organize outputs by output type rather than by trajectory.

Returns a Dictionary where keys are output names (e.g., :OutputPosition, :OutputVelocity) and values are Vectors containing the corresponding output from each trajectory.

This makes it easier to compare a specific output across all trajectories without needing to manually extract and collect data from individual trajectory dictionaries.

Example

# With SortByTrajectoryReduction (default):
# results = [traj1_dict, traj2_dict, traj3_dict]
# traj1_dict = Dictionary(:Time => ..., :OutputPosition => ..., :OutputVelocity => ...)
# traj2_dict = Dictionary(:Time => ..., :OutputPosition => ..., :OutputVelocity => ...)
# traj3_dict = Dictionary(:Time => ..., :OutputPosition => ..., :OutputVelocity => ...)

# With SortByOutputReduction:
# results = Dictionary(
#     :OutputPosition => [traj1_pos, traj2_pos, traj3_pos],
#     :OutputVelocity => [traj1_vel, traj2_vel, traj3_vel],
#     :Time => [traj1_time, traj2_time, traj3_time]
# )

Sum the outputs from each trajectory.

log_simulation_duration(duration_seconds)

Print the duration of a simulation in a human-readable format.

print_contents(container)

Print the contents of a struct to the console.

Output is of the form: fieldname = value

run_dynamics(sim::AbstractSimulation, tspan, distribution;
    output,
    selection::Union{Nothing,AbstractVector}=nothing,
    reduction=AppendReduction(),
    ensemble_algorithm=SciMLBase.EnsembleSerial(),
    algorithm=DynamicsMethods.select_algorithm(sim),
    trajectories=1,
    kwargs...
    )

Run trajectories for timespan tspan sampling from distribution.

Keywords

• output either a single function or a Tuple of functions with the signature f(sol, i) that takes the DifferentialEquations solution and returns the desired output quantity.
• selection should be an AbstractVector containing the indices to sample from the distribution. By default, nothing leads to random sampling.
• reduction defines how the data is reduced across trajectories. Options are AppendReduction(), MeanReduction(), SumReduction and FileReduction(filename).
• ensemble_algorithm is the algorithm from DifferentialEquations which determines which form of parallelism is used.
• algorithm is the algorithm used to integrate the equations of motion.
• trajectories is the number of trajectories to perform.
• savetime saves the simulation time-steps, useful when usings with integrators with variable time-stepping.
• precompile_dynamics runs a single step of the dynamics simulation in order to optimise the full run, exploits a strange issue with the Julia compiler.
• kwargs... any additional keywords are passed to DifferentialEquations solve`.

sample_distribution(sim::AbstractSimulation, distribution::DynamicalDistribution, i)

Generate initial conditions for a dynamics simulation as a selection, i, from the provided distribution of nuclear degrees of freedom. Simulation cache is updated to according to the sampled positions.

A container of dynamics variables are created from the intial condtions and returned in the format of a ComponentVector.

sample_distribution(sim::AbstractSimulation, distribution::DynamicalDistribution)

Generate initial conditions for a dynamics simulation by randomly sampling from the provided distribution of nuclear degrees of freedom. Simulation cache is updated to according to the sampled positions.

A container of dynamics variables are created from the intial condtions and returned in the format of a ComponentVector.

sample_distribution(sim::AbstractSimulation, distribution::ProductDistribution, i)

Generate initial conditions for a dynamics simulation as a selection, i, from the provided product distribution of nuclear degrees of freedom and the electronic state. Simulation cache is updated to according to the sampled positions.

A container of dynamics variables are created from the intial condtions and returned in the format of a ComponentVector.

sample_distribution(sim::AbstractSimulation, distribution::ProductDistribution)

Generate initial conditions for a dynamics simulation by randomly sampling from the provided product distribution of nuclear degrees of freedom and the electronic state. Simulation cache is updated to according to the sampled positions.

A container of dynamics variables are created from the intial condtions and returned in the format of a ComponentVector.