HASEonGPU.Simulation

class HASEonGPU.Simulation(gainMedium, pump, phiASE, timeIntegrationSolver, timeStep, crossSections=None, endTime=None, constants=<factory>, enableAse=True, prePump=False)

Bases: object

High-level pump, ASE, fluorescence, and time-integration loop.

Register onInit or beforeStep callbacks when a function needs the live Simulation object and may inspect or mutate it. Register onStep callbacks when a function needs the completed TimeStepState snapshot produced by each step.

Parameters:
gainMedium: GainMedium

Geometry, material data, and current beta arrays.

pump: PumpProperties

Pump model that adds population to betaCells.

phiASE: PhiASE

ASE configuration and execution handle.

timeIntegrationSolver: TimeIntegrationSolver

Solver object that advances betaCells using d beta / dt.

timeStep: float

Physical time increment per step, in seconds.

crossSections: CrossSectionData | None = None

Shared spectra used by pump and ASE when not set on either object.

endTime: float | None = None

Optional target physical time for runUntil().

constants: Constants

Physical constants used by the pump integrator.

enableAse: bool = True

Whether each derivative evaluation runs ASE depletion through PhiASE.

prePump: bool = False

When true, the first time step advances without ASE so pump can seed beta.

onStep(callback, *args, **kwargs)

Register a post-step callback.

The callback signature is callback(state, *args, **kwargs). Simulation always supplies the completed TimeStepState as the first argument, then appends the positional and keyword arguments passed to onStep. For example, simulation.onStep(write_vtk, output_dir, scale=5.5) calls write_vtk(state, output_dir, scale=5.5) after every completed step.

Use this hook for logging, writing VTK files, explicit state storage, or other work that should consume the immutable step snapshot. Callback return values are ignored. The method returns self so registrations can be chained.

onInit(callback, *args, **kwargs)

Register a one-time initialization callback.

The callback signature is callback(simulation, *args, **kwargs). Simulation supplies the live simulation object as the first argument, then appends the user arguments passed to onInit. The hook runs once, immediately before the first step is evaluated.

Use this hook to initialize or normalize mutable simulation inputs such as gainMedium, pump, phiASE, or timeStep. Callback return values are ignored. The method returns self for chaining.

beforeStep(callback, *args, **kwargs)

Register a pre-step callback.

The callback signature is callback(simulation, *args, **kwargs). Simulation supplies the live simulation object as the first argument, then appends the user arguments passed to beforeStep. The hook runs before every step, after one-time onInit callbacks.

Use this hook for controlled changes that must happen before derivative evaluation, such as time-dependent pump settings. Callback return values are ignored. The method returns self for chaining.

runUntil(endtime=None, endTime=None, *, openpmdSession=None)

Advance steps until the configured or supplied end time is reached.

runSteps(steps, pumpSteps=None, *, openpmdSession=None)

Run exactly steps calls to step() and return self.

pumpSteps optionally limits the pump contribution to the first pumpSteps calls in this run. When omitted, PumpProperties may provide a pumpSteps custom property. If neither is set, the pump is active for every step, matching the historical runSteps(steps) behavior. PumpProperties.pumpSubsteps is separate: it controls the internal pump integration resolution inside one pumped simulation step.

step(*, openpmdSession=None)

Advance one time step and return the completed TimeStepState.

getLastState()

Return the most recent completed TimeStepState snapshot.

getResults()

Return the most recent completed TimeStepState snapshot.

Simulation does not retain a full time-step history. Register an onStep callback to write or store per-step state explicitly.

property lastState

Most recent completed TimeStepState snapshot.

property time

Current physical simulation time in seconds.

property stepIndex

Number of completed time steps.