stochtraj

stochtraj_jump

Simulation of stochastic jump trajectories using a Markov state model.

Syntax

stochtraj_jump(Sys)
stochtraj_jump(Sys,Par)
stochtraj_jump(Sys,Par,Opt)
[t,RTraj] = stochtraj_jump(...)
[t,stateTraj] = stochtraj_jump(...)
[t,RTraj,qTraj,stateTraj] = stochtraj_jump(...)

Description

stochtraj_jump computes stochastic trajectories of Markovian jumps between specified molecular orientations represented by quaternions.

stochtraj_jump accepts up to three input arguments

Sys: dynamic properties
Par: (optional) simulation parameters for monte carlo integrator and trajectories
Opt: (optional) simulation options

If no input argument is given, a short help summary is shown (same as when typing help stochtraj_jump).

Depending on the input options, up to three output arguments are returned:

t: time axis, in seconds
RTraj: trajectories in terms of rotation matrices
qTraj: trajectories in terms of quaternions
stateTraj: trajectories in terms of Markov states (integer)

If no output argument is given, stochtraj_jump plots one of the trajectories.

Input: System dynamics

Sys is a structure containing the dynamic properties for generating the stochastic trajectories. Many of its fields overlap with those of chili. This allows the user to easily simulate EPR spectra in both frequency and time domains for comparison.

To dictate the inter- and intra-state dynamics, either TransRates or TransProb can be given, with the former taking precedence if both are given.

TransRates

Transition rate matrix of size (nStates,nStates), in seconds^-1. The elements of Sys.TransRates must satisfy the following properties:

all diagonal elements must be non-positive
all off-diagonal elements must be non-negative
all columns must sum to zero

TransProb

Transition probability matrix of size (nStates,nStates). The elements of Sys.TransProb must satisfy the following properties:

all elements must be non-negative
all columns must sum to one

Orientations

An array of Euler angles representing the orientation of each state, size (nStates,1) or (1,nStates).

Input: Simulation parameters

Par is a structure containing the parameters for calculating the stochastic trajectories. The parameters can be categorized into two groups: Monte Carlo settings and trajectory settings.

The Monte Carlo settings specify the parameters used to perform the time integration in the simulation. One can provide a number of steps nSteps and a time step dt or a total time for simulation tmax and a time step dt.

Note that, regardless of the combination of inputs that are used from below, a time step Par.dt must be given explicitly.

dt

The time step of the integration, in seconds.

nSteps

The total number of time steps used to perform integration.

tmax

The total time of the simulation, in seconds.

Lastly, the trajectory settings are used to specify the number of trajectories to be simulated, nTraj, and the starting states of each trajectory StatesStart.

StatesStart

Starting states for each trajectory, given as an array of size (1,nTraj).

nTraj

The total number of trajectories to simulate.

If only one starting state is given and nTraj is greater than one, then this starting state will be used for each trajectory. If StatesStart is not provided, then the starting states will be chosen uniformly at random with replacement. If nTraj is not provided, only one trajectory will be simulated.

Input: Simulation options

Opt is a structure with additional simulation options.

statesOnly

0 (default), 1
If equal to 1, only return the trajectories of Markov states, in which case Sys.States need not be specified.

Verbosity

0 (default), 1
Determines how much information stochtraj_jump prints to the screen. If Opt.Verbosity=0, it is completely silent. 1 prints details about the progress of the computation.

Example

To simulate a 200-ns long trajectory of Markovian jumps between the north and south poles with equal transition rates of 1x10⁹ s^-1, use

Sys.TransRates = 1e9*[-1,  1;
                       1, -1];  % transition rate matrix, in s^-1
Sys.Orientations = [0,  0, 0;
                    0, pi, 0];  % Euler angles of Markov states
            
Par.dt = 1e-9;       % size of time step, in s
Par.nSteps = 200;    % number of time steps

[t, RTraj] = stochtraj_jump(Sys,Par);

To simulate 400, 1-μs long trajectories of Markovian jumps between 2 orientations chosen uniformly at random, with equal probability of staying in a particular state or jumping to the other state, use

Sys.TransProb = [0.5, 0.5;
                 0.5, 0.5];           % transition probability matrix
Sys.Orientations = [2*pi*rand(2,1), 
                      pi*rand(2,1), 
                    2*pi*rand(2,1)];  % Euler angles of Markov states
            
Par.dt = 1e-9;       % size of time step, in s
Par.nSteps = 1000;    % number of time steps
Par.nTraj = 400;

[t, RTraj] = stochtraj_jump(Sys,Par);