cascade.sim

cascade.sim#

class cascade.sim#

The simulation class.

This class acts as a container for a collection of spherical particles, propagating their states in time according to user-defined dynamical equations and accounting for collisions and/or conjunctions.

The state of each particle is described by the following quantities:

the three Cartesian positions \(x\), \(y\) and \(z\),
the three Cartesian velocities \(v_x\), \(v_y\) and \(v_z\),
the particle radius \(s\).

The dynamical equations describing the evolution in time of \(\left( x,y,z,v_x,v_y,v_z \right)\) can be formulated via the heyoka.py expression system. Alternatively, ready-made dynamical equations for a variety of use cases are available in the cascade.dynamics module.

Methods

`__init__`(state, ct[, dyn, reentry_radius, ...])	Constructor.
`propagate_until`(t)	Attempts to advance the simulation time to t.
`remove_particles`(idxs)	Removes particles from the simulation.
`reset_conjunctions`()	Reset the conjunctions list.
`set_new_state_pars`(new_state[, new_pars])	Sets new values for the simulation state and parameters.
`step`()	Performs a single step of the simulation.

Attributes

`coll_whitelist`	Collision whitelist.
`compact_mode`	Compact mode.
`conj_thresh`	Conjunction threshold.
`conj_whitelist`	Conjunction whitelist.
`conjunctions`	Conjunctions recorded during the simulation.
`ct`	Collisional time.
`exit_radius`	Exit radius.
`high_accuracy`	High-accuracy mode.
`interrupt_info`	Interrupt info.
`min_coll_radius`	Minimum collisional radius.
`n_par_ct`	Number of collisional timesteps to be processed in parallel.
`npars`	Number of runtime paramenters.
`nparts`	Number of particles.
`pars`	Values of the runtime parameters appearing in the objects dynamics.
`reentry_radius`	The radius of the reentry domain.
`state`	State of all the particles currently in the simulation.
`time`	Current simulation time.
`tol`	Numerical integration tolerance.

__init__(state: numpy.ndarray[numpy.double], ct: float, dyn: Optional[List[Tuple[heyoka.expression, heyoka.expression]]] = None, reentry_radius: Optional[float | List[float]] = None, exit_radius: Optional[float] = None, pars: Optional[numpy.ndarray[numpy.double]] = None, tol: Optional[float] = None, high_accuracy: bool = False, compact_mode: bool = False, n_par_ct: int = 1, conj_thresh: float = 0.0, min_coll_radius: float = 0.0, coll_whitelist: Set[int] = set(), conj_whitelist: Set[int] = set())#

Constructor.

The only two mandatory arguments for the constructor are the initial state and the collisional timestep. Several additional configuration options for the simulation can be specified either at or after construction.

Parameters:

state (numpy.ndarray[numpy.double]) –
The initial state vector for the simulation. Must be a two-dimensional array of shape \(n\times 7\), where the number of rows \(n\) is the number of particles in the simulation, the first 6 columns contain the cartesian state variables \(\left( x,y,z,v_x,v_y,v_z \right)\) of each particle, and the seventh column contains the particle sizes.

After construction, the state vector can be accessed via the state attribute.
ct (float) – The length in time units of the collisional timestep. Must be positive and finite. After construction, the collisional timestep can be changed at any time via the ct attribute.
dyn (Optional[List[Tuple[heyoka.expression, heyoka.expression]]] = None) –
The particles’ dynamical equations. By default, the dynamics is purely Keplerian (see cascade.dynamics.kepler()).

Note that the dynamical equations cannot be changed after construction.
reentry_radius (Optional[float | List[float]] = None) –
The radius of the reentry domain. If a single scalar is provided, then the reentry domain is a sphere of the given radius centred in the origin. If a list of 3 values is provided, then the reentry domain is a triaxial ellipsoid centred in the origin whose three semi-axes lengths \(\left( a,b,c \right)\) are given by the values in the list.

When a particle enters the reentry domain, a reentry event is triggered and the simulation is stopped. If no reentry radius is provided (the default), then no reentry events are possible.
exit_radius (Optional[float] = None) – Exit radius. If provided, the simulation will track the distance of all particles from the origin, and when a particle’s distance from the origin exceeds the provided limit, the simulation will stop with an exit event. By default, no exit radius is defined.
pars (Optional[numpy.ndarray[numpy.double]] = None) –
Values of the dynamical parameters. If the particles’ dynamical equations contain runtime parameters, their values can be provided via this argument, which must be a two-dimensional array of shape \(n\times N_p\), where \(n\) is the number of particles in the simulation and \(N_p\) is the number of runtime parameters appearing in the dynamical equations. Each row in the array contains the values of the runtime parameters for the dynamics of the corresponding particle.

If this argument is not provided (the default), then all runtime parameters for all particles are initialised to zero. Note that the values of the runtime parameters can be changed at any time via the pars attribute.
tol (Optional[float] = None) – The tolerance used when numerically solving the dynamical equations. If not provided, it defaults to the double-precision epsilon (\(\sim 2.2\times 10^{-16}\)).
high_accuracy (bool = False) – High-accuracy mode. If enabled, the numerical integrator will employ techniques to minimise the accumulation of floating-point truncation errors, at the price of a small performance penalty. This can be useful to maintain high accuracy in long-running simulations.
compact_mode (bool = False) – Compact mode. If enabled, the just-in-time compilation process will manipulate efficiently also very long expression for the dynamics. This is useful, for example, when using long expansions to model distrubances, or when gravity is modelled via mascon models. This comes at the price of a performance penalty (~<x2) in the resulting numerical integrator.
n_par_ct (int = 1) – Number of collisional timesteps to be processed in parallel. This is a tuning parameter that, while not affecting the correctness of the simulation, can greatly influence its performance. The optimal value of this parameter depends heavily on the specifics of the simulation, and thus users are advised to experiment with different values to determine which one works best.
conj_thresh (float = 0.0) – Conjunction threshold. Conjunctions are tracked only if the conjunction distance is less than this threshold. By default, this value is set to zero, which means that conjunction tracking is disabled. The conjunction threshold can be changed at any time via the conj_thresh attribute.
min_coll_radius (float = 0.0) – Minimum collisional radius. A collision between two particles is detected only if the radius of at least one particle is greater than this value. By default, this value is zero, which means that only collisions between point-like particles are skipped. If this value is set to \(+\infty\), then collision detection is disabled for all particles. The minimum collisional radius can be changed at any time via the min_coll_radius attribute.
coll_whitelist (Set[int] = set()) – Collision whitelist. If not empty, then a collision between two particles is detected only if at least one particle is in the whitelist. By default, the collision whitelist is empty, which means that the whitelisting mechanism is disabled. The collision whitelist can be changed at any time via the coll_whitelist attribute.
conj_whitelist (Set[int] = set()) – Conjunction whitelist. If not empty, then a conjunction between two particles is detected only if at least one particle is in the whitelist. By default, the conjunction whitelist is empty, which means that the whitelisting mechanism is disabled. The conjunction whitelist can be changed at any time via the conj_whitelist attribute.

property coll_whitelist#

Collision whitelist.

This set contains the list of particles considered during the detection of collision events. If this list is empty, then all particles are considered during the detection of collision events.

property compact_mode#

Compact mode.

If enabled, the just-in-time compilation process will manipulate efficiently also very long expression for the dynamics. This is useful, for example, when using long expansions to model distrubances, or when gravity is modelled via mascon models. This comes at the price of a performance penalty (~<x2) in the resulting numerical integrator. Compact mode cannot be changed after construction.

property conj_thresh#

Conjunction threshold.

Conjunctions are tracked only if the conjunction distance is less than this threshold. By default, this value is set to zero, which means that conjunction tracking is disabled. The conjunction threshold can be changed at any time.

property conj_whitelist#

Conjunction whitelist.

This set contains the list of particles considered during the detection of conjunction events. If this list is empty, then all particles are considered during the detection of conjunction events.

property conjunctions#

Conjunctions recorded during the simulation.

A read-only attribute containing all the conjunction events. The events are stored in a structured array containing the following records:

i, (int): id of the first particle involved in the conjunction event,
j, (int): id of the first particle involved in the conjunction event,
t, (float): time of the conjunction event,
dist, (float): closest approach distance,
state_i, (ndarray): state (\(x,y,z,vx,vy,vz\)) of the first particle at the conjunction,
state_j, (ndarray): state (\(x,y,z,vx,vy,vz\)) of the second particle at the conjunction.

Whenever the cascade simulation is made with a conj_thresh larger than its default zero value, all conjunction events of whitelisted objects (or of all objects in case no whitelist is provided) are detected and tracked. A conjunction event will not stop the simulation hence the user cannot ‘react’ to it.

property ct#

Collisional time.

This float represents the length in time units of the collisional timestep. Must be positive and finite. It can be set and its value will be used in the next call to the propagation methods (such as cascade.sim.step() and cascade.sim.propagate_until()).

property exit_radius#

Exit radius.

If an exit radius is provided upon construction, the simulation will track the distance of all particles from the origin, and when a particle’s distance from the origin exceeds this limit, the simulation will stop with an exit event. By default, no exit radius is defined and this attribute contains the scalar 0.

property high_accuracy#

High-accuracy mode.

If enabled, the numerical integrator will employ techniques to minimise the accumulation of floating-point truncation errors, at the price of a small performance penalty. This can be useful to maintain high accuracy in long-running simulations. High-accuracy mode cannot be changed after construction.

property interrupt_info#

Interrupt info.

Returns the information on the outcome of the latest call to the propagation methods of the sim class (such as cascade.sim.step() and cascade.sim.propagate_until()).

The possible values of this attribute are:

None: the propagation method finished successfully and no stopping event was detected;
(i, j) (a pair of integers): the propagation method stopped due to the collision between particles i and j;
i (a single integer): particle i either entered the reentry domain or exited the simulation domain;
(i, tm) (integer + time coordinate): a non-finite state was detected for particle i at time tm.

property min_coll_radius#

Minimum collisional radius.

A collision between two particles is detected only if the radius of at least one particle is greater than this value. By default, this value is zero, which means that only collisions between point-like particles are skipped. If this value is set to \(+\infty\), then collision detection is disabled for all particles. The minimum collisional radius can be changed at any time.

property n_par_ct#

Number of collisional timesteps to be processed in parallel.

This is a tuning parameter that, while not affecting the correctness of the simulation, can greatly influence its performance. The optimal value of this parameter depends heavily on the specifics of the simulation, and thus users are advised to experiment with different values to determine which one works best.

property npars#

Number of runtime paramenters.

A read-only attribute containing the number of runtime parameters in the dynamics \(N_p\).

property nparts#

Number of particles.

A read-only attribute containing the current number of particles. The number of particles ina simulation can be controlled by removing particles via methods such as remove_particles() or set_new_state_pars().

property pars#

Values of the runtime parameters appearing in the objects dynamics.

The parameters are stored in a two-dimensional ndarray of shape \(n\times N_p\), where \(n\) is the number of particles in the simulation and \(N_p\) is the number of runtime parameters appearing in the dynamical equations.

While this is a read-only property (in the sense that it is not possible to set a new array of runtime parameters via this property), the values contained in the array CAN be written to.

propagate_until(t: float) → cascade.outcome#

Attempts to advance the simulation time to t.

Cascade will try to advance the simulation time to the value given. If stopping events trigger in such a time interval, the simulation will stop and set its state/time at the epoch the first event was triggered.

Parameters:: t (float) – The propagation time.
Returns:: The outcome of the propagation.
Return type:: cascade.outcome

property reentry_radius#

The radius of the reentry domain.

The reentry domain is modelled either as a sphere (in which case this property will be a single scalar representing the radius of the reentry sphere) or as a triaxial ellipsoid (in which case this property will be a list of three values representing the three semi-axes lengths \(\left( a,b,c \right)\) of the ellipsoid). If no reentry radius was specified upon construction, this attribute contains the scalar 0.

remove_particles(idxs: List[int]) → None#

Removes particles from the simulation.

This takes care to remove all the particles and their corresponding parameters.

Parameters:: idxs (List[int]) – The indices of the particles to be removed.

reset_conjunctions() → None#

Reset the conjunctions list.

Clears the ndarray storing conjunctions events, thus freeing all associated memory. This is useful in very long simulations where the number of conjunction events can grow substantially. The user can then store them in some other form, or extract relevant statistics to then reset the conjunctions.

set_new_state_pars(new_state: numpy.ndarray, new_pars: numpy.ndarray = None) → None#

Sets new values for the simulation state and parameters.

If no pars are passed only the state will be set and all parameters, if present, will be set to zero.

Note that this method should be used only if you need to alter the number of particles in the simulation. If you all you need to do is to change the state and/or parameter values for one or more particles, you can write directly into state and pars.

Parameters:

new_state (numpy.ndarray) – The new state for all particles (the shape must be \(n \times 7\)).
new_pars (numpy.ndarray = None) – The new runtime parameters for the dynamics of all particles (the shape must be \(n \times N_p\)).

property state#

State of all the particles currently in the simulation.

The state is stored in a two-dimensional ndarray of shape \(n\times 7\), where the number of rows \(n\) is the number of particles in the simulation, the first 6 columns contain the cartesian state variables \(\left( x,y,z,v_x,v_y,v_z \right)\) of each particle, and the seventh column contains the particle sizes.

While this is a read-only property (in the sense that it is not possible to set a new array of runtime parameters via this property), the values contained in the array CAN be written to.

step() → cascade.outcome#

Performs a single step of the simulation.

Cascade will try to advance the simulation time by ct times n_par_ct time units. If stopping events (e.g., collision, reentry, etc.) trigger in such a time interval, the simulation will stop and set its state/time at the epoch the first event was triggered.

Returns:: The outcome of the simulation step.
Return type:: cascade.outcome

property time#

Current simulation time.

This float contains the value of the current simulation time. It can be set, and it is referred to in the dynamics equation as heyoka.time.

property tol#

Numerical integration tolerance.

The tolerance used when numerically solving the dynamical equations. If not provided, it defaults to the double-precision epsilon (\(\sim 2.2\times 10^{-16}\)). The integration tolerance cannot be changed after construction.

cascade.sim

Contents

cascade.sim#