mpacts.particles. photonpacket

In order to be able to use this module import it like this:

import mpacts.particles
#or assign it to a shorter name
import mpacts.particles as prt

PhotonPacket Layout

Particle of type PhotonPacket:

  • x (Point)
  • xt (Point)
  • direction (Vector)
  • packet_size (Scalar)
  • delta_packet_size (Scalar)
  • step_size (Scalar)
  • ut (Scalar)
  • alive (int)
  • layer_index (int)
  • sphere_index (int)
  • rel_step_size_done (Scalar)
  • previous_step_size (Scalar)
  • hit_boundary (int)
  • step_size_reduction (int)
  • normal (Vector)
  • GeometryTag = GeometryTag_Ray

Supported Commands

On the particle container following list of commands can be invoked.

Note

the pc keyword argument is passed automatically, as well as the parent if the pc is created with a parent.

mypc.AABBGeneratorCmd()
Command that generates a list of bounding boxes for known geometries.
Default location: ‘loop_cmds/pre_contact_cmds’
  • Required keywords:
    • pc — Particle container on which the command is applied
  • Optional keywords:
    • gate (default value = ET::ChildProperty const*) — Can decide to (temporarily) not execute the command in a CommandList. (Default is ExecuteAlways)
    • margin (default value = 0) — Adds an additional (fixed size) margin to the bounding box. Useful to give planes a third dimension, or to provide margin, so the contacts don’t need to be detected every timestep
    • predicate (default value = None) — Predicate that will decide whether this command is executed for a specific particle, when absent the command is executed for every particle.
  • additional parameters (to quickly choose a gate to be applied):
    • executeOnce: If True, will set the ExecuteOnce gate
    • executeEvery: If given, will execute every “executeEvery” time-steps.
    • executeInterval: If given, will execute every interval seconds (approximate simulation time)
    • executeTimes: If given, will execute at times specified in the list provided (approximated to the nearest discrete time step!)
    • executeEveryPCSizeChange If given, will execute every time a specified particle container changes size.
  • parent: Can be set to ‘False’ or ‘0’ to explicitely prevent the command to be added to the (simulation) commandlist.
mypc.AbsorbCmd()
Command that computes a change in ‘packet_size’ based on background absorption. The change is added to the ‘delta_packet_size’ array, and the user is stillresponsible to use Euler time integration to actually update the ‘packet_size’ array at the end of the ‘timestep’
Default location: ‘loop_cmds/body_force_cmds’
  • Required keywords:
    • alb — Absorption parameter.
    • pc — Particle container on which the command is applied
  • Optional keywords:
    • gate (default value = ET::ChildProperty const*) — Can decide to (temporarily) not execute the command in a CommandList. (Default is ExecuteAlways)
    • predicate (default value = None) — Predicate that will decide whether this command is executed for a specific particle, when absent the command is executed for every particle.
  • additional parameters (to quickly choose a gate to be applied):
    • executeOnce: If True, will set the ExecuteOnce gate
    • executeEvery: If given, will execute every “executeEvery” time-steps.
    • executeInterval: If given, will execute every interval seconds (approximate simulation time)
    • executeTimes: If given, will execute at times specified in the list provided (approximated to the nearest discrete time step!)
    • executeEveryPCSizeChange If given, will execute every time a specified particle container changes size.
  • parent: Can be set to ‘False’ or ‘0’ to explicitely prevent the command to be added to the (simulation) commandlist.
mypc.ComputeStepSizeCmd()
Command to compute the step size of photon packets based on their ‘ut’ array, and as sampled from a logarithmic distribution.
Default location: ‘loop_cmds/pre_body_force_cmds’
  • Required keywords:
    • pc — Particle container on which the command is applied
  • Optional keywords:
    • gate (default value = ET::ChildProperty const*) — Can decide to (temporarily) not execute the command in a CommandList. (Default is ExecuteAlways)
    • predicate (default value = None) — Predicate that will decide whether this command is executed for a specific particle, when absent the command is executed for every particle.
  • additional parameters (to quickly choose a gate to be applied):
    • executeOnce: If True, will set the ExecuteOnce gate
    • executeEvery: If given, will execute every “executeEvery” time-steps.
    • executeInterval: If given, will execute every interval seconds (approximate simulation time)
    • executeTimes: If given, will execute at times specified in the list provided (approximated to the nearest discrete time step!)
    • executeEveryPCSizeChange If given, will execute every time a specified particle container changes size.
  • parent: Can be set to ‘False’ or ‘0’ to explicitely prevent the command to be added to the (simulation) commandlist.
mypc.PCStatisticsCmd()
PCStatistics command
Default location: ‘loop_cmds/pre_contact_cmds/Periodic_BC_CopyToGhost_PeriodicBoundary1D’
  • Required keywords:
    • pc — Particle container on which the command is applied
  • Optional keywords:
    • gate (default value = ET::ChildProperty const*) — Can decide to (temporarily) not execute the command in a CommandList. (Default is ExecuteAlways)
    • predicate (default value = None) — Predicate that will decide whether this command is executed for a specific particle, when absent the command is executed for every particle.
  • additional parameters (to quickly choose a gate to be applied):
    • executeOnce: If True, will set the ExecuteOnce gate
    • executeEvery: If given, will execute every “executeEvery” time-steps.
    • executeInterval: If given, will execute every interval seconds (approximate simulation time)
    • executeTimes: If given, will execute at times specified in the list provided (approximated to the nearest discrete time step!)
    • executeEveryPCSizeChange If given, will execute every time a specified particle container changes size.
  • parent: Can be set to ‘False’ or ‘0’ to explicitely prevent the command to be added to the (simulation) commandlist.
mypc.RecycleCmd()
Command that recycles particles flagged as non-alive using the array ‘alive’. The command accepts one or two generator instances that produce the initial data for the newly created photon packets. This command will also ensure that particles will be actually killed if the number of already recycled particles exceeds a user-given value. Ideally this command is executed as the very first thing the loop_cmds.
Default location: ‘loop_cmds/pre_body_force_cmds’
  • Required keywords:
    • generator1 — First generator for recycling ‘death’ particles.
    • pc — Particle container on which the command is applied
  • Optional keywords:
    • Nmax (default value = -1) — Maximum number of particles to revive. If < 0, there is no maximum.
    • gate (default value = ET::ChildProperty const*) — Can decide to (temporarily) not execute the command in a CommandList. (Default is ExecuteAlways)
    • generator2 (default value = None) — Second generator for recycling ‘death’ particles.
    • p_gen1 (default value = 1) — Probability of using generator 1. If ‘1’, a second generator does not need to be provided. The probability of using the second generator will be 1-p_gen1
    • predicate (default value = None) — Predicate that will decide whether this command is executed for a specific particle, when absent the command is executed for every particle.
  • Read only properties:
    • N — Total number of recycled particles. (display to monitor amount of simulated photons)
  • additional parameters (to quickly choose a gate to be applied):
    • executeOnce: If True, will set the ExecuteOnce gate
    • executeEvery: If given, will execute every “executeEvery” time-steps.
    • executeInterval: If given, will execute every interval seconds (approximate simulation time)
    • executeTimes: If given, will execute at times specified in the list provided (approximated to the nearest discrete time step!)
    • executeEveryPCSizeChange If given, will execute every time a specified particle container changes size.
  • parent: Can be set to ‘False’ or ‘0’ to explicitely prevent the command to be added to the (simulation) commandlist.
mypc.RegularSparseGridToScalarArrayCmd()
Command that sets the Scalar value of a given array to the value of the grid cell corresponding to its position.
Default location: ‘loop_cmds/pre_integration_cmds’
  • Required keywords:
    • array — Array in which regular grid values will be stored
    • grid — Regular grid with elements of the same type as array that we will assemble the values towards
    • pc — Particle container on which the command is applied
  • Optional keywords:
    • gate (default value = ET::ChildProperty const*) — Can decide to (temporarily) not execute the command in a CommandList. (Default is ExecuteAlways)
    • predicate (default value = None) — Predicate that will decide whether this command is executed for a specific particle, when absent the command is executed for every particle.
    • x (default value = None) — Array with positions for each value in ‘array’ that will be used to locate the proper grid cell. If not provided, the array with name ‘x’ will be searched in the particle container
  • additional parameters (to quickly choose a gate to be applied):
    • executeOnce: If True, will set the ExecuteOnce gate
    • executeEvery: If given, will execute every “executeEvery” time-steps.
    • executeInterval: If given, will execute every interval seconds (approximate simulation time)
    • executeTimes: If given, will execute at times specified in the list provided (approximated to the nearest discrete time step!)
    • executeEveryPCSizeChange If given, will execute every time a specified particle container changes size.
  • parent: Can be set to ‘False’ or ‘0’ to explicitely prevent the command to be added to the (simulation) commandlist.
mypc.RouletteCmd()
Command to activate a ‘Roulette’ which will either kill a particle or increase its weight with the inverse probability, so as low-weight photon packets can be removed properly from the simulation.
Default location: ‘loop_cmds/post_integration_cmds’
  • Required keywords:
    • p — Probability of removing the particle in the roulette.
    • packet_size_crit — Critical packet size (weight) below which the roulette will be activated
    • pc — Particle container on which the command is applied
  • Optional keywords:
    • gate (default value = ET::ChildProperty const*) — Can decide to (temporarily) not execute the command in a CommandList. (Default is ExecuteAlways)
    • predicate (default value = None) — Predicate that will decide whether this command is executed for a specific particle, when absent the command is executed for every particle.
  • additional parameters (to quickly choose a gate to be applied):
    • executeOnce: If True, will set the ExecuteOnce gate
    • executeEvery: If given, will execute every “executeEvery” time-steps.
    • executeInterval: If given, will execute every interval seconds (approximate simulation time)
    • executeTimes: If given, will execute at times specified in the list provided (approximated to the nearest discrete time step!)
    • executeEveryPCSizeChange If given, will execute every time a specified particle container changes size.
  • parent: Can be set to ‘False’ or ‘0’ to explicitely prevent the command to be added to the (simulation) commandlist.
mypc.ScalarArrayToRegularFullGridCmd()
Command that assembles a given ‘Scalar’ type array to a regular full grid with Scalar values, based on a given position array ‘x’ that corresponds to ‘array’.
Default location: ‘loop_cmds/pre_integration_cmds’
  • Required keywords:
    • array — Array which will be assembled to the regular grid
    • grid — Regular grid with elements of the same type as array that we will assemble the values towards
    • pc — Particle container on which the command is applied
  • Optional keywords:
    • gate (default value = ET::ChildProperty const*) — Can decide to (temporarily) not execute the command in a CommandList. (Default is ExecuteAlways)
    • predicate (default value = None) — Predicate that will decide whether this command is executed for a specific particle, when absent the command is executed for every particle.
    • x (default value = None) — Array with positions for each value in ‘array’ that will be used to locate the proper grid cell. If not provided, the array with name ‘x’ will be searched in the particle container
  • additional parameters (to quickly choose a gate to be applied):
    • executeOnce: If True, will set the ExecuteOnce gate
    • executeEvery: If given, will execute every “executeEvery” time-steps.
    • executeInterval: If given, will execute every interval seconds (approximate simulation time)
    • executeTimes: If given, will execute at times specified in the list provided (approximated to the nearest discrete time step!)
    • executeEveryPCSizeChange If given, will execute every time a specified particle container changes size.
  • parent: Can be set to ‘False’ or ‘0’ to explicitely prevent the command to be added to the (simulation) commandlist.
mypc.ScalarArrayToRegularSparseGridCmd()
Command that assembles a given ‘Scalar’ type array to a regular grid with Scalar values, based on a given position array ‘x’ that corresponds to ‘array’.
Default location: ‘loop_cmds/pre_integration_cmds’
  • Required keywords:
    • array — Array which will be assembled to the regular grid
    • grid — Regular grid with elements of the same type as array that we will assemble the values towards
    • pc — Particle container on which the command is applied
  • Optional keywords:
    • gate (default value = ET::ChildProperty const*) — Can decide to (temporarily) not execute the command in a CommandList. (Default is ExecuteAlways)
    • predicate (default value = None) — Predicate that will decide whether this command is executed for a specific particle, when absent the command is executed for every particle.
    • x (default value = None) — Array with positions for each value in ‘array’ that will be used to locate the proper grid cell. If not provided, the array with name ‘x’ will be searched in the particle container
  • additional parameters (to quickly choose a gate to be applied):
    • executeOnce: If True, will set the ExecuteOnce gate
    • executeEvery: If given, will execute every “executeEvery” time-steps.
    • executeInterval: If given, will execute every interval seconds (approximate simulation time)
    • executeTimes: If given, will execute at times specified in the list provided (approximated to the nearest discrete time step!)
    • executeEveryPCSizeChange If given, will execute every time a specified particle container changes size.
  • parent: Can be set to ‘False’ or ‘0’ to explicitely prevent the command to be added to the (simulation) commandlist.
mypc.ScatterCmd()
Command to compute scattering based on parameter ‘g’.
Default location: ‘loop_cmds/body_force_cmds’
  • Required keywords:
    • g — Scattering strength(?) ‘g’.
    • pc — Particle container on which the command is applied
  • Optional keywords:
    • gate (default value = ET::ChildProperty const*) — Can decide to (temporarily) not execute the command in a CommandList. (Default is ExecuteAlways)
    • predicate (default value = None) — Predicate that will decide whether this command is executed for a specific particle, when absent the command is executed for every particle.
  • additional parameters (to quickly choose a gate to be applied):
    • executeOnce: If True, will set the ExecuteOnce gate
    • executeEvery: If given, will execute every “executeEvery” time-steps.
    • executeInterval: If given, will execute every interval seconds (approximate simulation time)
    • executeTimes: If given, will execute at times specified in the list provided (approximated to the nearest discrete time step!)
    • executeEveryPCSizeChange If given, will execute every time a specified particle container changes size.
  • parent: Can be set to ‘False’ or ‘0’ to explicitely prevent the command to be added to the (simulation) commandlist.
mypc.StepIntegration_ForwardEuler_Cmd()
Integration of arrays ‘x’ and ‘dx’ using a user-given array with ‘Scalar’ type steps.
Default location: ‘loop_cmds/pre_body_force_cmds’
  • Required keywords:
    • dx — The value ‘dx’ (usually unit vector) that gets integrated as dest = x + step*dx
    • pc — Particle container on which the command is applied
    • step — The (always Scalar) step size
    • x — The value ‘x’ that needs to be integrated as dest = x+ step*dx
  • Optional keywords:
    • dest (default value = None) — Destination arrray. If not given, ‘x’ will simply be used. Must be same type as x
    • gate (default value = ET::ChildProperty const*) — Can decide to (temporarily) not execute the command in a CommandList. (Default is ExecuteAlways)
    • predicate (default value = None) — Predicate that will decide whether this command is executed for a specific particle, when absent the command is executed for every particle.
  • additional parameters (to quickly choose a gate to be applied):
    • executeOnce: If True, will set the ExecuteOnce gate
    • executeEvery: If given, will execute every “executeEvery” time-steps.
    • executeInterval: If given, will execute every interval seconds (approximate simulation time)
    • executeTimes: If given, will execute at times specified in the list provided (approximated to the nearest discrete time step!)
    • executeEveryPCSizeChange If given, will execute every time a specified particle container changes size.
  • parent: Can be set to ‘False’ or ‘0’ to explicitely prevent the command to be added to the (simulation) commandlist.
mypc.TimeIntegration_ForwardEuler_Generic_Cmd()
Time integration for any arrays ‘x’ and ‘dx’ belonging to the same manager, vector or scalar.
Default location: ‘loop_cmds/integration_cmds’
  • Required keywords:
    • dx — The value ‘dx’ that gets integrated as x += dx*dt
    • pc — Particle container on which the command is applied
    • x — The value ‘x’ that needs to be integrated as x += dx*dt
  • Optional keywords:
    • gate (default value = ET::ChildProperty const*) — Can decide to (temporarily) not execute the command in a CommandList. (Default is ExecuteAlways)
    • predicate (default value = None) — Predicate that will decide whether this command is executed for a specific particle, when absent the command is executed for every particle.
    • timestep (default value = 0) — timestep used by this time integration command
  • additional parameters (to quickly choose a gate to be applied):
    • executeOnce: If True, will set the ExecuteOnce gate
    • executeEvery: If given, will execute every “executeEvery” time-steps.
    • executeInterval: If given, will execute every interval seconds (approximate simulation time)
    • executeTimes: If given, will execute at times specified in the list provided (approximated to the nearest discrete time step!)
    • executeEveryPCSizeChange If given, will execute every time a specified particle container changes size.
  • parent: Can be set to ‘False’ or ‘0’ to explicitely prevent the command to be added to the (simulation) commandlist.
mypc.VTKWriterCmd()
Writer of VTK (.vtp/vtu) files. The writer acts on the data member given in the constructor. By default all child array managers are written, but without their additional data arrays (such as for instance ‘r’, ‘v’, ...) this can be changed by invoking the ‘select_all’ member function.
Also individual arrays can be selected by adding a ‘enable_VTK_write’ child (‘ r.add_child( BaseObject(‘enable_VTK_write’)’), or they can be unselected by adding a ‘disable_VTK_write’ child.
Conforming to what ParaView expects, symmetric tensors are written as diagonal values, then upper triangle:
0 3 4
x 1 5
x x 2.
If you write a full matrix, however, the order is as in our c++ code, i.e.:
0 1 2
3 4 5
6 7 8.
Has no default location.
  • Required keywords:
    • data — The root of which the data will be written
    • filename — The base filename of the files that will be written. A number will be appended to differentiate between different timesteps.
  • Optional keywords:
    • gate (default value = ET::ChildProperty const*) — Can decide to (temporarily) not execute the command in a CommandList. (Default is ExecuteAlways)
    • select_all (default value = 0) — Determines whether the writer tries to write as much as possible or not (by default false). Note: for legacy reasons there is also a named function for this.
    • start_index (default value = 0) — Index of the next file that will be written. The index of each subsequent file will be incremented by one. Default is zero.
  • additional parameters (to quickly choose a gate to be applied):
    • executeOnce: If True, will set the ExecuteOnce gate
    • executeEvery: If given, will execute every “executeEvery” time-steps.
    • executeInterval: If given, will execute every interval seconds (approximate simulation time)
    • executeTimes: If given, will execute at times specified in the list provided (approximated to the nearest discrete time step!)
    • executeEveryPCSizeChange If given, will execute every time a specified particle container changes size.
  • parent: Can be set to ‘False’ or ‘0’ to explicitely prevent the command to be added to the (simulation) commandlist.