# Integrator related modules

Basic code for the templated integrators.

Currently we only support two-step integrators.

These classes are used to generate the code for the actual integrators from the sph_eval module.

class `pysph.sph.integrator.``EPECIntegrator`(**kw)

  Bases: `pysph.sph.integrator.Integrator`

  Predictor corrector integrators can have two modes of operation.

  In the Evaluate-Predict-Evaluate-Correct (EPEC) mode, the system is advanced using:

  \[ \begin{align}\begin{aligned}F(y^n) --> Evaluate\\y^{n+\frac{1}{2}} = y^n + F(y^n) --> Predict\\F(y^{n+\frac{1}{2}}) --> Evaluate\\y^{n+1} = y^n + \Delta t F(y^{n+\frac{1}{2}}) --> Correct\end{aligned}\end{align} \]

  Notes:

  The Evaluate stage of the integrator forces a function evaluation. Therefore, the PEC mode is much faster but relies on old accelertions for the Prediction stage.

  In the EPEC mode, the final corrector can be modified to:

  :math:`y^{n+1} = y^n + frac{Delta t}{2}left( F(y^n) +
    F(y^{n+frac{1}{2}}) right)`

  This would require additional storage for the accelerations.

  Pass fluid names and suitable IntegratorStep instances.

  For example:

      >>> integrator = Integrator(fluid=WCSPHStep(), solid=WCSPHStep())

  where “fluid” and “solid” are the names of the particle arrays.

  `one_timestep`(t, dt)

    User written function that actually does one timestep.

    This function is used in the high-performance Cython implementation. The assumptions one may make are the following:

    > - t and dt are passed.

    > - the following methods are available:

    >   > - self.initialize()
    >   > - self.stage1(), self.stage2() etc. depending on the number of stages available.
    >   > - self.compute_accelerations(index=0, update_nnps=True)
    >   > - self.do_post_stage(stage_dt, stage_count_from_1)
    >   > - self.update_domain()

    Please see any of the concrete implementations of the Integrator class to study. By default the Integrator implements a predict-evaluate-correct method, the same as PECIntegrator.

class `pysph.sph.integrator.``EulerIntegrator`(**kw)

  Bases: `pysph.sph.integrator.Integrator`

  Pass fluid names and suitable IntegratorStep instances.

  For example:

      >>> integrator = Integrator(fluid=WCSPHStep(), solid=WCSPHStep())

  where “fluid” and “solid” are the names of the particle arrays.

  `one_timestep`(t, dt)

    User written function that actually does one timestep.

    This function is used in the high-performance Cython implementation. The assumptions one may make are the following:

    > - t and dt are passed.

    > - the following methods are available:

    >   > - self.initialize()
    >   > - self.stage1(), self.stage2() etc. depending on the number of stages available.
    >   > - self.compute_accelerations(index=0, update_nnps=True)
    >   > - self.do_post_stage(stage_dt, stage_count_from_1)
    >   > - self.update_domain()

    Please see any of the concrete implementations of the Integrator class to study. By default the Integrator implements a predict-evaluate-correct method, the same as PECIntegrator.

class `pysph.sph.integrator.``Integrator`(**kw)

  Bases: `object`

  Generic class for multi-step integrators in PySPH for a system of ODES of the form \(\frac{dy}{dt} = F(y)\).

  Pass fluid names and suitable IntegratorStep instances.

  For example:

      >>> integrator = Integrator(fluid=WCSPHStep(), solid=WCSPHStep())

  where “fluid” and “solid” are the names of the particle arrays.

  `compute_accelerations`(index=0, update_nnps=True)
  `compute_h_minimum`()
  `compute_time_step`(dt, cfl)

    If there are any adaptive timestep constraints, the appropriate timestep is returned, else None is returned.

  `initial_acceleration`(t, dt)

    Compute the initial accelerations if needed before the iterations start.

    The default implementation only does this for the first acceleration evaluator. So if you have multiple evaluators, you must override this method in a subclass.

  `one_timestep`(t, dt)

    User written function that actually does one timestep.

    This function is used in the high-performance Cython implementation. The assumptions one may make are the following:

    > - t and dt are passed.

    > - the following methods are available:

    >   > - self.initialize()
    >   > - self.stage1(), self.stage2() etc. depending on the number of stages available.
    >   > - self.compute_accelerations(index=0, update_nnps=True)
    >   > - self.do_post_stage(stage_dt, stage_count_from_1)
    >   > - self.update_domain()

    Please see any of the concrete implementations of the Integrator class to study. By default the Integrator implements a predict-evaluate-correct method, the same as PECIntegrator.

  `set_acceleration_evals`(a_evals)

    Set the acceleration evaluators.

    This must be done before the integrator is used.

    If you are using the SPHCompiler, it automatically calls this method.

  `set_compiled_object`(c_integrator)

    Set the high-performance compiled object to call internally.

  `set_fixed_h`(fixed_h)
  `set_nnps`(nnps)
  `set_parallel_manager`(pm)
  `set_post_stage_callback`(callback)

    This callback is called when the particles are moved, i.e one stage of the integration is done.

    This callback is passed the current time value, the timestep and the stage.

    The current time value is t + stage_dt, for example this would be 0.5*dt for a two stage predictor corrector integrator.

  `step`(time, dt)

    This function is called by the solver.

    To implement the integration step please override the `one_timestep` method.

  `update_domain`()

    Update the domain of the simulation.

    This is to be called when particles move so the ghost particles (periodicity, mirror boundary conditions) can be reset. Further, this also recalculates the appropriate cell size based on the particle kernel radius, h. This should be called explicitly when desired but usually this is done when the particles are moved or the h is changed.

    The integrator should explicitly call this when needed in the one_timestep method.

class `pysph.sph.integrator.``LeapFrogIntegrator`(**kw)

  Bases: `pysph.sph.integrator.PECIntegrator`

  A leap-frog integrator.

  Pass fluid names and suitable IntegratorStep instances.

  For example:

      >>> integrator = Integrator(fluid=WCSPHStep(), solid=WCSPHStep())

  where “fluid” and “solid” are the names of the particle arrays.

  `one_timestep`(t, dt)

    User written function that actually does one timestep.

    This function is used in the high-performance Cython implementation. The assumptions one may make are the following:

    > - t and dt are passed.

    > - the following methods are available:

    >   > - self.initialize()
    >   > - self.stage1(), self.stage2() etc. depending on the number of stages available.
    >   > - self.compute_accelerations(index=0, update_nnps=True)
    >   > - self.do_post_stage(stage_dt, stage_count_from_1)
    >   > - self.update_domain()

    Please see any of the concrete implementations of the Integrator class to study. By default the Integrator implements a predict-evaluate-correct method, the same as PECIntegrator.

class `pysph.sph.integrator.``PECIntegrator`(**kw)

  Bases: `pysph.sph.integrator.Integrator`

  In the Predict-Evaluate-Correct (PEC) mode, the system is advanced using:

  \[ \begin{align}\begin{aligned}y^{n+\frac{1}{2}} = y^n + \frac{\Delta t}{2}F(y^{n-\frac{1}{2}}) --> Predict\\F(y^{n+\frac{1}{2}}) --> Evaluate\\y^{n + 1} = y^n + \Delta t F(y^{n+\frac{1}{2}})\end{aligned}\end{align} \]

  Pass fluid names and suitable IntegratorStep instances.

  For example:

      >>> integrator = Integrator(fluid=WCSPHStep(), solid=WCSPHStep())

  where “fluid” and “solid” are the names of the particle arrays.

  `one_timestep`(t, dt)

    User written function that actually does one timestep.

    This function is used in the high-performance Cython implementation. The assumptions one may make are the following:

    > - t and dt are passed.

    > - the following methods are available:

    >   > - self.initialize()
    >   > - self.stage1(), self.stage2() etc. depending on the number of stages available.
    >   > - self.compute_accelerations(index=0, update_nnps=True)
    >   > - self.do_post_stage(stage_dt, stage_count_from_1)
    >   > - self.update_domain()

    Please see any of the concrete implementations of the Integrator class to study. By default the Integrator implements a predict-evaluate-correct method, the same as PECIntegrator.

class `pysph.sph.integrator.``PEFRLIntegrator`(**kw)

  Bases: `pysph.sph.integrator.Integrator`

  A Position-Extended Forest-Ruth-Like integrator [Omeylan2002]

  References

  [Omeylan2002] | I.M. Omelyan, I.M. Mryglod and R. Folk, “Optimized Forest-Ruth- and Suzuki-like algorithms for integration of motion in many-body systems”, Computer Physics Communications 146, 188 (2002) http://arxiv.org/abs/cond-mat/0110585

  Pass fluid names and suitable IntegratorStep instances.

  For example:

      >>> integrator = Integrator(fluid=WCSPHStep(), solid=WCSPHStep())

  where “fluid” and “solid” are the names of the particle arrays.

  `one_timestep`(t, dt)

    User written function that actually does one timestep.

    This function is used in the high-performance Cython implementation. The assumptions one may make are the following:

    > - t and dt are passed.

    > - the following methods are available:

    >   > - self.initialize()
    >   > - self.stage1(), self.stage2() etc. depending on the number of stages available.
    >   > - self.compute_accelerations(index=0, update_nnps=True)
    >   > - self.do_post_stage(stage_dt, stage_count_from_1)
    >   > - self.update_domain()

    Please see any of the concrete implementations of the Integrator class to study. By default the Integrator implements a predict-evaluate-correct method, the same as PECIntegrator.

class `pysph.sph.integrator.``TVDRK3Integrator`(**kw)

  Bases: `pysph.sph.integrator.Integrator`

  In the TVD-RK3 integrator, the system is advanced using:

  \[ \begin{align}\begin{aligned}y^{n + \frac{1}{3}} = y^n + \Delta t F( y^n )\\y^{n + \frac{2}{3}} = \frac{3}{4}y^n + \frac{1}{4}(y^{n + \frac{1}{3}} + \Delta t F(y^{n + \frac{1}{3}}))\\y^{n + 1} = \frac{1}{3}y^n + \frac{2}{3}(y^{n + \frac{2}{3}} + \Delta t F(y^{n + \frac{2}{3}}))\end{aligned}\end{align} \]

  Pass fluid names and suitable IntegratorStep instances.

  For example:

      >>> integrator = Integrator(fluid=WCSPHStep(), solid=WCSPHStep())

  where “fluid” and “solid” are the names of the particle arrays.

  `one_timestep`(t, dt)

    User written function that actually does one timestep.

    This function is used in the high-performance Cython implementation. The assumptions one may make are the following:

    > - t and dt are passed.

    > - the following methods are available:

    >   > - self.initialize()
    >   > - self.stage1(), self.stage2() etc. depending on the number of stages available.
    >   > - self.compute_accelerations(index=0, update_nnps=True)
    >   > - self.do_post_stage(stage_dt, stage_count_from_1)
    >   > - self.update_domain()

    Please see any of the concrete implementations of the Integrator class to study. By default the Integrator implements a predict-evaluate-correct method, the same as PECIntegrator.

Integrator steps for different schemes.

Implement as many stages as needed.

class `pysph.sph.integrator_step.``ADKEStep`

  Bases: `pysph.sph.integrator_step.IntegratorStep`

  Predictor Corrector integrator for Gas-dynamics ADKE

  `initialize`(d_idx, d_x0, d_y0, d_z0, d_x, d_y, d_z, d_u0, d_v0, d_w0, d_u, d_v, d_w, d_e, d_e0, d_rho, d_rho0)
  `stage1`(d_idx, d_x0, d_y0, d_z0, d_x, d_y, d_z, d_u0, d_v0, d_w0, d_u, d_v, d_w, d_e0, d_e, d_au, d_av, d_aw, d_ae, d_rho, d_rho0, d_arho, dt)
  `stage2`(d_idx, d_x0, d_y0, d_z0, d_x, d_y, d_z, d_u0, d_v0, d_w0, d_u, d_v, d_w, d_e0, d_e, d_au, d_av, d_aw, d_ae, dt)

class `pysph.sph.integrator_step.``AdamiVerletStep`

  Bases: `pysph.sph.integrator_step.IntegratorStep`

  Verlet time integration described in A generalized wall boundary condition for smoothed particle hydrodynamics 2012, JCP, 231, pp 7057–7075

  This integrator can operate in either PEC mode or in EPEC mode as described in the paper.

  `initialize`()
  `stage1`(d_idx, d_u, d_v, d_w, d_au, d_av, d_aw, d_x, d_y, d_z, dt)
  `stage2`(d_idx, d_u, d_v, d_w, d_au, d_av, d_aw, d_x, d_y, d_z, d_rho, d_arho, d_vmag2, dt)

class `pysph.sph.integrator_step.``EulerStep`

  Bases: `pysph.sph.integrator_step.IntegratorStep`

  Fast but inaccurate integrator. Use this for testing

  `stage1`(d_idx, d_u, d_v, d_w, d_au, d_av, d_aw, d_x, d_y, d_z, d_rho, d_arho, dt)

class `pysph.sph.integrator_step.``GSPHStep`

  Bases: `pysph.sph.integrator_step.IntegratorStep`

  `stage1`(d_idx, d_x, d_y, d_z, d_u, d_v, d_w, d_e, d_au, d_av, d_aw, d_ae, dt)

class `pysph.sph.integrator_step.``GasDFluidStep`

  Bases: `pysph.sph.integrator_step.IntegratorStep`

  Predictor Corrector integrator for Gas-dynamics

  `initialize`(d_idx, d_x0, d_y0, d_z0, d_x, d_y, d_z, d_h, d_u0, d_v0, d_w0, d_u, d_v, d_w, d_e, d_e0, d_h0, d_converged, d_omega, d_rho, d_rho0, d_alpha1, d_alpha2, d_alpha10, d_alpha20)
  `stage1`(d_idx, d_x0, d_y0, d_z0, d_x, d_y, d_z, d_u0, d_v0, d_w0, d_u, d_v, d_w, d_e0, d_e, d_au, d_av, d_aw, d_ae, d_rho, d_rho0, d_arho, d_h, d_h0, d_ah, d_alpha1, d_aalpha1, d_alpha10, d_alpha2, d_aalpha2, d_alpha20, dt)
  `stage2`(d_idx, d_x0, d_y0, d_z0, d_x, d_y, d_z, d_u0, d_v0, d_w0, d_u, d_v, d_w, d_e0, d_e, d_au, d_av, d_alpha1, d_aalpha1, d_alpha10, d_alpha2, d_aalpha2, d_alpha20, d_aw, d_ae, dt)

class `pysph.sph.integrator_step.``InletOutletStep`

  Bases: `pysph.sph.integrator_step.IntegratorStep`

  A trivial integrator for the inlet/outlet particles

  `initialize`()
  `stage1`(d_idx, d_x, d_y, d_z, d_u, d_v, d_w, dt)
  `stage2`(d_idx, d_x, d_y, d_z, d_u, d_v, d_w, dt)

class `pysph.sph.integrator_step.``IntegratorStep`

  Bases: `object`

  Subclass this and implement the methods `initialize`, `stage1` etc. Use the same conventions as the equations.

class `pysph.sph.integrator_step.``LeapFrogStep`

  Bases: `pysph.sph.integrator_step.IntegratorStep`

  Using this stepper with XSPH as implemented in pysph.base.basic_equations.XSPHCorrection is not directly possible and requires a nicer implementation where the correction alone is added to `ax, ay, az`.

  `stage1`(d_idx, d_x, d_y, d_z, d_u, d_v, d_w, d_ax, d_ay, d_az, dt)
  `stage2`(d_idx, d_x, d_y, d_z, d_u, d_au, d_v, d_av, d_w, d_aw, d_ax, d_ay, d_az, d_rho, d_arho, d_e, d_ae, dt)

class `pysph.sph.integrator_step.``OneStageRigidBodyStep`

  Bases: `pysph.sph.integrator_step.IntegratorStep`

  Simple one stage rigid-body motion

  `initialize`(d_idx, d_x, d_y, d_z, d_x0, d_y0, d_z0, d_u, d_v, d_w, d_u0, d_v0, d_w0)
  `stage1`(d_idx, d_x, d_y, d_z, d_x0, d_y0, d_z0, d_u, d_v, d_w, d_u0, d_v0, d_w0, d_au, d_av, d_aw, dt)
  `stage2`(d_idx, d_x, d_y, d_z, d_x0, d_y0, d_z0, d_u, d_v, d_w, d_u0, d_v0, d_w0, d_au, d_av, d_aw, dt)

class `pysph.sph.integrator_step.``PEFRLStep`

  Bases: `pysph.sph.integrator_step.IntegratorStep`

  Using this stepper with XSPH as implemented in pysph.base.basic_equations.XSPHCorrection is not directly possible and requires a nicer implementation where the correction alone is added to `ax, ay, az`.

  `stage1`(d_idx, d_x, d_y, d_z, d_u, d_v, d_w, d_ax, d_ay, d_az, dt)
  `stage2`(d_idx, d_x, d_y, d_z, d_u, d_au, d_v, d_av, d_w, d_aw, d_ax, d_ay, d_az, d_rho, d_arho, d_e, d_ae, dt=0.0)
  `stage3`(d_idx, d_x, d_y, d_z, d_u, d_au, d_v, d_av, d_w, d_aw, d_ax, d_ay, d_az, d_rho, d_arho, d_e, d_ae, dt=0.0)
  `stage4`(d_idx, d_x, d_y, d_z, d_u, d_au, d_v, d_av, d_w, d_aw, d_ax, d_ay, d_az, d_rho, d_arho, d_e, d_ae, dt=0.0)
  `stage5`(d_idx, d_x, d_y, d_z, d_u, d_au, d_v, d_av, d_w, d_aw, d_ax, d_ay, d_az, d_rho, d_arho, d_e, d_ae, dt=0.0)

class `pysph.sph.integrator_step.``SolidMechStep`

  Bases: `pysph.sph.integrator_step.IntegratorStep`

  Predictor corrector Integrator for solid mechanics problems

  `initialize`(d_idx, d_x0, d_y0, d_z0, d_x, d_y, d_z, d_u0, d_v0, d_w0, d_u, d_v, d_w, d_rho0, d_rho, d_s00, d_s01, d_s02, d_s11, d_s12, d_s22, d_s000, d_s010, d_s020, d_s110, d_s120, d_s220, d_e0, d_e)
  `stage1`(d_idx, d_x0, d_y0, d_z0, d_x, d_y, d_z, d_u0, d_v0, d_w0, d_u, d_v, d_w, d_rho0, d_rho, d_au, d_av, d_aw, d_ax, d_ay, d_az, d_arho, d_e, d_e0, d_ae, d_s00, d_s01, d_s02, d_s11, d_s12, d_s22, d_s000, d_s010, d_s020, d_s110, d_s120, d_s220, d_as00, d_as01, d_as02, d_as11, d_as12, d_as22, dt)
  `stage2`(d_idx, d_x0, d_y0, d_z0, d_x, d_y, d_z, d_u0, d_v0, d_w0, d_u, d_v, d_w, d_rho0, d_rho, d_au, d_av, d_aw, d_ax, d_ay, d_az, d_arho, d_e, d_ae, d_e0, d_s00, d_s01, d_s02, d_s11, d_s12, d_s22, d_s000, d_s010, d_s020, d_s110, d_s120, d_s220, d_as00, d_as01, d_as02, d_as11, d_as12, d_as22, dt)

class `pysph.sph.integrator_step.``TransportVelocityStep`

  Bases: `pysph.sph.integrator_step.IntegratorStep`

  Integrator defined in ‘A transport velocity formulation for smoothed particle hydrodynamics’, 2013, JCP, 241, pp 292–307

  For a predictor-corrector style of integrator, this integrator should operate only in PEC mode.

  `initialize`()
  `stage1`(d_idx, d_u, d_v, d_w, d_au, d_av, d_aw, d_uhat, d_auhat, d_vhat, d_avhat, d_what, d_awhat, d_x, d_y, d_z, dt)
  `stage2`(d_idx, d_u, d_v, d_w, d_au, d_av, d_aw, d_vmag2, dt)

class `pysph.sph.integrator_step.``TwoStageRigidBodyStep`

  Bases: `pysph.sph.integrator_step.IntegratorStep`

  Simple rigid-body motion

  At each stage of the integrator, the prescribed velocity and accelerations are incremented by dt/2.

  Note that the time centered velocity is used for updating the particle positions. This ensures exact motion for a constant acceleration.

  `initialize`(d_idx, d_x, d_y, d_z, d_x0, d_y0, d_z0, d_u, d_v, d_w, d_u0, d_v0, d_w0)
  `stage1`(d_idx, d_x, d_y, d_z, d_x0, d_y0, d_z0, d_u, d_v, d_w, d_u0, d_v0, d_w0, d_au, d_av, d_aw, dt)
  `stage2`(d_idx, d_x, d_y, d_z, d_x0, d_y0, d_z0, d_u, d_v, d_w, d_u0, d_v0, d_w0, d_au, d_av, d_aw, dt)

class `pysph.sph.integrator_step.``VelocityVerletSymplecticWCSPHStep`

  Bases: `pysph.sph.integrator_step.IntegratorStep`

  Another symplectic second order integrator described in the review paper by Monaghan:

  J. Monaghan, “Smoothed Particle Hydrodynamics”, Reports on Progress in Physics, 2005, 68, pp 1703–1759 [JM05]

  kick–drift–kick form of the verlet integrator

  `initialize`()
  `stage1`(d_idx, d_u, d_v, d_w, d_au, d_av, d_aw, dt)
  `stage2`(d_idx, d_x, d_y, d_z, d_u, d_v, d_w, d_au, d_av, d_aw, dt)

class `pysph.sph.integrator_step.``VerletSymplecticWCSPHStep`

  Bases: `pysph.sph.integrator_step.IntegratorStep`

  Symplectic second order integrator described in the review paper by Monaghan:

  J. Monaghan, “Smoothed Particle Hydrodynamics”, Reports on Progress in Physics, 2005, 68, pp 1703–1759 [JM05]

  Notes:

  This integrator should run in PEC mode since in the first stage, the positions are updated using the current velocity. The accelerations are then computed to advance to the full time step values.

  This version of the integrator does not update the density. That is, the summation density is used instead of the continuity equation.

  `initialize`()
  `stage1`(d_idx, d_x, d_y, d_z, d_u, d_v, d_w, dt)
  `stage2`(d_idx, d_x, d_y, d_z, d_ax, d_ay, d_az, d_u, d_v, d_w, d_au, d_av, d_aw, dt)

class `pysph.sph.integrator_step.``WCSPHStep`

  Bases: `pysph.sph.integrator_step.IntegratorStep`

  Standard Predictor Corrector integrator for the WCSPH formulation

  Use this integrator for WCSPH formulations. In the predictor step, the particles are advanced to t + dt/2. The particles are then advanced with the new force computed at this position.

  This integrator can be used in PEC or EPEC mode.

  The same integrator can be used for other problems. Like for example solid mechanics (see SolidMechStep)

  `initialize`(d_idx, d_x0, d_y0, d_z0, d_x, d_y, d_z, d_u0, d_v0, d_w0, d_u, d_v, d_w, d_rho0, d_rho)
  `stage1`(d_idx, d_x0, d_y0, d_z0, d_x, d_y, d_z, d_u0, d_v0, d_w0, d_u, d_v, d_w, d_rho0, d_rho, d_au, d_av, d_aw, d_ax, d_ay, d_az, d_arho, dt)
  `stage2`(d_idx, d_x0, d_y0, d_z0, d_x, d_y, d_z, d_u0, d_v0, d_w0, d_u, d_v, d_w, d_rho0, d_rho, d_au, d_av, d_aw, d_ax, d_ay, d_az, d_arho, dt)

class `pysph.sph.integrator_step.``WCSPHTVDRK3Step`

  Bases: `pysph.sph.integrator_step.IntegratorStep`

  TVD RK3 stepper for WCSPH

  This integrator requires \(2\) stages for the storage of the acceleration variables.

  `initialize`(d_idx, d_x0, d_y0, d_z0, d_x, d_y, d_z, d_u0, d_v0, d_w0, d_u, d_v, d_w, d_rho0, d_rho)
  `stage1`(d_idx, d_x0, d_y0, d_z0, d_x, d_y, d_z, d_u0, d_v0, d_w0, d_u, d_v, d_w, d_rho0, d_rho, d_au, d_av, d_aw, d_ax, d_ay, d_az, d_arho, dt)
  `stage2`(d_idx, d_x0, d_y0, d_z0, d_x, d_y, d_z, d_u0, d_v0, d_w0, d_u, d_v, d_w, d_rho0, d_rho, d_au, d_av, d_aw, d_ax, d_ay, d_az, d_arho, dt)
  `stage3`(d_idx, d_x0, d_y0, d_z0, d_x, d_y, d_z, d_u0, d_v0, d_w0, d_u, d_v, d_w, d_rho0, d_rho, d_au, d_av, d_aw, d_ax, d_ay, d_az, d_arho, dt)