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)

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)

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.

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)

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)

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.

class pyInclude.simulation.Simulation(gainMedium, pump, phiASE, timeIntegrationSolver, timeStep, crossSections=None, endTime=None, constants=<factory>, updateTerminalLevel=True)

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.

updateTerminalLevel: bool = True

Whether the last z-level beta values are advanced by the solver.

onStep(callback)

Register callback(state) to run after every completed step.

state is a TimeStepState containing copied result arrays such as betaCells, betaVolume, phiAse, dndtPump, and dndtAse. Callback return values are ignored.

onInit(callback)

Register callback(simulation) to run once before the first step.

The callback receives this live Simulation object, so it can read or change gainMedium, pump, phiASE, timeStep, and other simulation settings before any derivative is evaluated.

beforeStep(callback)

Register callback(simulation) to run before every step.

The callback receives this live Simulation object at the current time and stepIndex. Use this for controlled changes to inputs before the next time-step update.

runUntil(endtime=None, endTime=None)

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

runSteps(steps)

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

step()

Advance one time step and return the completed TimeStepState.

getResults()

Return all stored TimeStepState snapshots in step order.

property time

Current physical simulation time in seconds.

property stepIndex

Number of completed time steps.

pyInclude.simulation.TimeSteppedSimulation

alias of Simulation