mpacts.particles. sphparticle

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

SPHParticle Layout

Particle of type SPHParticle:

  • x (Point)
  • v (Vector)
  • F (Vector)
  • m (Scalar)
  • p (Scalar)
  • rho (Scalar)
  • drho (Scalar)
  • h (Scalar)
  • GeometryTag = GeometryTag_SPH

SPHParticle Example creation

Creating a particle container consisting of ‘SPHParticles’ can be done like this:

import mpacts.particles as prt
from mpacts.particles.SPHParticle import SPHParticle

SPHParticlepc = prt.ParticleContainer("SPHParticlepc", SPHParticle, mysim) #mysim is optional
particle = SPHParticlepc.add_particle()

particle.x = (1.0, 0.0, 1.0)
#or
mypc[0].x = (1.0, 0.0, 1.0)

#or to make a lot of particles
positions = [ (1.0, 0.0, 0.0), (1.0, 1.0, 1.0), (0.0, 1.0, 1.0) ]
SPHParticlepc.add_and_set_particles( x = positions ) #any number of other arrays may be set at the same time (r, v, ...)
                                            #and they can either have the same length as positions or length 1

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.AppliedForceCmd()
Applied user-specified force on a given particle or - if not given - on every particle in an ArrayManager
Default location: ‘loop_cmds/body_force_cmds’
  • Required keywords:
    • force (kg . m . s^-2) — Applied force vector
    • 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)
    • index (default value = -1) — Index of particle to which the force should be applied. If not given, force will be applied to all particles (possibly selected by the predicate)
    • 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.CSVWriterCmd()
Writer for CSV files for an arraymanager. The writer acts on the data member given in the constructor, which has to be an arraymanager. By default all arrays are written out, except those who have a disable_CSV_write child.
Default location: ‘loop_cmds/output_cmds’
  • Required keywords:
    • data — The manager of which the data will be written (CSV writer is not recursive!)
    • 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)
    • write_header (default value = 1) — Decides if a header is added or not.
    • write_index (default value = 0) — The current sequential number of the output file.
    • write_time (default value = 0) — Decides if a comment is added on the first line with the current time on it. (Paraview does not like this!).
  • 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.DirectedForceCmd()
Force with fixed magnitude in a direction given by the user-given array ‘direction’
Default location: ‘loop_cmds/body_force_cmds’
  • Required keywords:
    • direction — Array with a direction vector
    • magnitude (kg . m . s^-2) — Magnitude of the applied force
    • 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)
    • normalize (default value = 0) — If ‘True’, the direction vector will first be normalized
    • 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.
    • use_contact_area (default value = 0) — If ‘True’, the contact area array will be used to weight the obtained directed force
  • 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.EOSMonaghanCmd()
Equation of state following the monaghan formulation.
Default location: ‘loop_cmds/pre_body_force_cmds’
  • Required keywords:
    • B — B constant in the Monaghan expression (measure of stiffness)
    • pc — Particle container on which the command is applied
    • rho0 — reference density
  • Optional keywords:
    • gamma (default value = 7) — gamma constant in the Monaghan expression (exponent)
    • gate (default value = ET::ChildProperty const*) — Can decide to (temporarily) not execute the command in a CommandList. (Default is ExecuteAlways)
    • p_background (default value = 0) — background pressure
    • 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.GravityCmd()
Gravitation command. Computes a force F=m*g, with ‘m’ a mass array and ‘g’ the gravitational acceleration vector. Note that this command implicitly assumes that the center of gravity is (0,0,0) in body frame coordinates, and therefore does not apply a gravitational moment.
Default location: ‘loop_cmds/body_force_cmds’
  • Required keywords:
    • pc — Particle container on which the command is applied
  • Optional keywords:
    • g (m . s^-2) (default value = 0 -9.81 0) — The gravitational vector
    • 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.RandomForceCmd()
Force in a fully random direction drawn from uniform distribution over unit sphere surface with a magnitude following a normal distribution with given standard deviation sigma. Note: It is not equivalent to the Brownian motion.
Default location: ‘loop_cmds/body_force_cmds’
  • Required keywords:
    • pc — Particle container on which the command is applied
    • sigma — Standard deviation of the Random force magnitude; if sigma<0, we keep a unit-vector.
  • Optional keywords:
    • array_name (default value = F) — Name of the array to operate on (default: ‘F’). Note: this option is kept for legacy reasons. Please use pass property ‘force_array’ instead
    • direction (1) (default value = 0 0 0) — If given, this axis (plus and minus) will be used for the random force, with only its magnitude randomized.
    • force_array (default value = None) — Array to which the force should be added. If not given, array with name ‘array_name’ will be used.
    • 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.
    • restrict_to_plane (1) (default value = 0 0 0) — If a plane normal is given, the command will project its direction in the plane.
  • 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.SetContactMatrixDiagonalCmd()
Sets an array with a single value. Used for instance to zero forces and moments every timestep. Properties are ‘value’, and an ‘array’ that needs to be set.
Default location: ‘loop_cmds/pre_body_force_cmds’
  • Required keywords:
    • array — The array that will be set using the given value.
    • value — The value that will be used to set the array.
  • 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 decided whether or not the command is executed for a specific particle index (if omitted, the command is executed for all particle indices)
  • 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.SetMeanToOriginCmd()
Centers the positions of particles in a particle container to a user specified ‘center’.
Default location: ‘loop_cmds/integration_cmds’
  • Required keywords:
    • pc — Particle container on which the command is applied
  • Optional keywords:
    • center (default value = 0 0 0) — Position at which the x array should be centered
    • gate (default value = ET::ChildProperty const*) — Can decide to (temporarily) not execute the command in a CommandList. (Default is ExecuteAlways)
    • omit_axis (default value = -1) — This axis will not be used to center the positions
    • 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_centered (default value = None) — Array where the centered positions will be stored. If not provided, the same array as the property ‘x’ will be used
    • x (default value = None) — Array with positions
  • 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.TimeIntegration_ForwardEuler_Translation_Cmd()
Time integration
Default location: ‘loop_cmds/integration_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.
    • 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.TimeIntegration_LeapFrog_Translation_Cmd()
Time integration
Default location: ‘loop_cmds/integration_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.
    • 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.