pyInclude.simulation

High-level Python simulation wrapper around pump, ASE, and time stepping.

class pyInclude.simulation.PhiASE(config=None, crossSections=None, spectralProperties=None, laserProperties=None, gainMedium=None, minRaysPerSample=100000, maxRaysPerSample=100000, mseThreshold=0.1, repetitions=4, adaptiveSteps=4, useReflections=True, monochromatic=False, backend=None, parallelMode='single', numDevices=1, nPerNode=1, writeVtk=False, devices=<factory>, minSampleRange=None, maxSampleRange=None, rngSeed=None)

Bases: object

Configure and run the ASE flux calculation for one gain-medium state.

Simulation normally owns this object and calls run(...) during each time-step derivative evaluation. Advanced users can also call run directly with a GainMedium and CrossSectionData object.

Parameters:

  • config (object | None)

  • crossSections (CrossSectionData | None)

  • spectralProperties (CrossSectionData | None)

  • laserProperties (LaserProperties | None)

  • gainMedium (GainMedium | None)

  • minRaysPerSample (int)

  • maxRaysPerSample (int)

  • mseThreshold (float)

  • repetitions (int)

  • adaptiveSteps (int)

  • useReflections (bool)

  • monochromatic (bool)

  • backend (str)

  • parallelMode (str)

  • numDevices (int)

  • nPerNode (int)

  • writeVtk (bool)

  • devices (list[int])

  • minSampleRange (int | None)

  • maxSampleRange (int | None)

  • rngSeed (int | None)

config: object | None = None

Optional YAML filename or mapping with PhiASE run-control settings.

crossSections: CrossSectionData | None = None

Absorption/emission spectra used by the ASE calculation.

spectralProperties: CrossSectionData | None = None

Alias for crossSections kept for the public spectral API.

laserProperties: LaserProperties | None = None

Lower-level laser property store accepted by legacy workflows.

gainMedium: GainMedium | None = None

Optional medium stored for direct run() calls.

minRaysPerSample: int = 100000

Minimum Monte Carlo rays launched for each beta sample.

maxRaysPerSample: int = 100000

Maximum rays per sample allowed during adaptive refinement.

mseThreshold: float = 0.1

Target mean-squared-error threshold for adaptive ASE sampling.

repetitions: int = 4

Maximum repeated ASE estimates at a fixed ray count.

adaptiveSteps: int = 4

Number of ray-count increases between min and max rays.

useReflections: bool = True

Whether top/bottom surface reflectivities affect ray propagation.

monochromatic: bool = False

Use only the first spectral samples instead of wavelength integration.

backend: str = None

Alpaka backend name; inspect valid strings with AlpakaBackends.all().

parallelMode: str = 'single'

direct binding single or MPI launcher mpi.

Type:

Execution mode

numDevices: int = 1

Maximum compute devices made available to the lower-level run.

nPerNode: int = 1

MPI launcher ranks per node when parallelMode is mpi.

writeVtk: bool = False

Request VTK output from lower-level compute paths when supported.

devices: list[int]

Optional explicit device ids passed to the lower-level compute path.

minSampleRange: int | None = None

Inclusive first flattened beta sample processed by ASE.

maxSampleRange: int | None = None

Inclusive last flattened beta sample processed by ASE.

rngSeed: int | None = None

Optional RNG seed for reproducible Monte Carlo sampling.

classmethod fromYaml(filename, **overrides)

Create a PhiASE configuration from YAML plus Python overrides.

static addArguments(parser)

Add command-line arguments that map to PhiASE settings.

classmethod fromArgs(args, **overrides)

Create a PhiASE configuration from parsed argparse results.

run(gainMedium=None, crossSections=None)

Run ASE for the supplied or configured GainMedium.

Returns self. Use getResults() afterwards to access the raw lower-level result, including phiAse.

getResults()

Return the raw ASE result from the most recent run(...) call.

property experimentParameters

Low-level experiment parameters built for the last run(...).

property computeParameters

Low-level compute parameters built for the last run(...).

property hostMesh

Low-level host mesh built from the last GainMedium input.

class pyInclude.simulation.LegacyGridDataBetaVolumeMapper(method='linear')

Bases: object

Map point-centered betaCells to prism-centered betaVolume.

map(medium)

Return prism-centered betaVolume for the supplied medium.

class pyInclude.simulation.TimeStepState(step, time, betaCells, betaVolume, phiAse, dndtAse, dndtPump, aseResult, topology=None)

Bases: object

Snapshot handed to onStep callbacks after a completed time step.

The arrays are copies of the simulation outputs at step/time. betaCells and phiAse are point-by-level arrays with shape (numberOfPoints, numberOfLevels). betaVolume is prism-centered with shape (numberOfTriangles, numberOfLevels - 1).

Parameters:

  • step (int)

  • time (float)

  • betaCells (ndarray)

  • betaVolume (ndarray)

  • phiAse (ndarray | None)

  • dndtAse (ndarray)

  • dndtPump (ndarray)

  • aseResult (object | None)

  • topology (object | None)

step: int

Completed one-based step index.

time: float

Physical simulation time after the step, in seconds.

betaCells: ndarray

Excited-state fraction at mesh points and z-levels.

betaVolume: ndarray

Excited-state fraction interpolated to wedge-prism centers.

phiAse: ndarray | None

ASE flux at mesh points and z-levels, or None if unavailable.

dndtAse: ndarray

ASE depletion contribution to d beta / dt.

dndtPump: ndarray

Pump contribution to d beta / dt.

aseResult: object | None

Raw lower-level ASE result object for advanced inspection.

topology: object | None = None

Static mesh topology used by geometry-aware state callbacks.

class pyInclude.simulation.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)

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

runSteps(steps, pumpSteps=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()

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.

pyInclude.simulation.TimeSteppedSimulation

alias of Simulation