pyInclude.timeIntegration

Time-integration solvers for the point-level beta population arrays.

class pyInclude.timeIntegration.TimeDerivative(betaCells, dndtPump, dndtAse, derivative, tau, phiAse=None, aseResult=None)

Bases: object

Derivative evaluation produced during one time-integration stage.

Simulation builds this object from pump gain, ASE depletion, and fluorescence decay. Custom solvers receive it from their rhs callback while trying candidate betaCells values.

Parameters:

  • betaCells (ndarray)

  • dndtPump (ndarray)

  • dndtAse (ndarray)

  • derivative (ndarray)

  • tau (float)

  • phiAse (ndarray | None)

  • aseResult (object | None)

betaCells: ndarray

Point-level excited-state fraction used for this RHS evaluation.

dndtPump: ndarray

Pump source contribution to d beta / dt in 1 / s.

dndtAse: ndarray

ASE depletion contribution to d beta / dt in 1 / s.

derivative: ndarray

Total d beta / dt advanced by the time solver.

tau: float

Fluorescence lifetime used for spontaneous decay, in seconds.

phiAse: ndarray | None = None

ASE flux \(\Phi_i\) from the derivative evaluation, if available.

aseResult: object | None = None

Raw lower-level ASE result object, if available.

class pyInclude.timeIntegration.TimeIntegrationResult(betaCells, evaluation)

Bases: object

Return object from TimeIntegrationSolver.step(...).

Parameters:
betaCells: ndarray

Updated point-level beta array proposed by the solver.

evaluation: TimeDerivative

Derivative evaluation to expose in the resulting TimeStepState.

class pyInclude.timeIntegration.TimeIntegrationSolver

Bases: object

Base protocol for custom beta time-integration solvers.

Implement step(rhs, betaCells, time, timeStep). rhs is a callable that accepts (betaCells, time) and returns a TimeDerivative. Higher order solvers may call rhs several times for one public simulation step.

step(rhs, betaCells, time, timeStep)

Return a TimeIntegrationResult for one physical time step.

time and timeStep are in seconds. betaCells has the same shape as GainMedium.get("betaCells").expectedShape.

class pyInclude.timeIntegration.ExplicitEuler

Bases: TimeIntegrationSolver

First-order explicit Euler beta update using one RHS evaluation.

step(rhs, betaCells, time, timeStep)

Return a TimeIntegrationResult for one physical time step.

time and timeStep are in seconds. betaCells has the same shape as GainMedium.get("betaCells").expectedShape.

class pyInclude.timeIntegration.Heun

Bases: TimeIntegrationSolver

Second-order predictor-corrector beta update using two RHS evaluations.

step(rhs, betaCells, time, timeStep)

Return a TimeIntegrationResult for one physical time step.

time and timeStep are in seconds. betaCells has the same shape as GainMedium.get("betaCells").expectedShape.

class pyInclude.timeIntegration.Midpoint

Bases: TimeIntegrationSolver

Second-order midpoint beta update using a half-step RHS evaluation.

step(rhs, betaCells, time, timeStep)

Return a TimeIntegrationResult for one physical time step.

time and timeStep are in seconds. betaCells has the same shape as GainMedium.get("betaCells").expectedShape.

class pyInclude.timeIntegration.RungeKutta4

Bases: TimeIntegrationSolver

Classical fourth-order Runge-Kutta beta update using four RHS evaluations.

step(rhs, betaCells, time, timeStep)

Return a TimeIntegrationResult for one physical time step.

time and timeStep are in seconds. betaCells has the same shape as GainMedium.get("betaCells").expectedShape.

class pyInclude.timeIntegration.ImplicitEuler(iterations=8, tolerance=1e-10)

Bases: TimeIntegrationSolver

Fixed-point implicit Euler beta update for stiff beta dynamics.

step(rhs, betaCells, time, timeStep)

Return a TimeIntegrationResult for one physical time step.

time and timeStep are in seconds. betaCells has the same shape as GainMedium.get("betaCells").expectedShape.

class pyInclude.timeIntegration.ExponentialEuler

Bases: TimeIntegrationSolver

Euler source update with analytical fluorescence decay over timeStep.

step(rhs, betaCells, time, timeStep)

Return a TimeIntegrationResult for one physical time step.

time and timeStep are in seconds. betaCells has the same shape as GainMedium.get("betaCells").expectedShape.