simulation¶

Simulation classes used by pyMARS.

Provides an abstract BaseSimulation along with concrete simulation types: IgnitionSimulation (autoignition) and FlameSimulation (one-dimensional laminar flame). Additional types can be added by subclassing BaseSimulation.

class pymars.simulation.BaseSimulation(idx, properties, model, phase_name='', path='')¶

Common interface and shared behavior for a single simulation case.

Parameters:

idx (int) – Identifier index for case
properties (InputIgnition or InputLaminarFlame) – Object with initial conditions for the simulation
model (str) – Filename for Cantera-format model to be used
phase_name (str, optional) – Optional name for phase to load from YAML file (e.g., ‘gas’).
path (str, optional) – Path for location of output files

abstractmethod calculate()¶: Run the case and return only its global metric, without sampling data.

clean()¶

Remove the intermediate data file written during the run, if any.

Simulation types that write no data file leave save_file as None, so this is a no-op for them and the same call works regardless of type.

num_sample_points = 20¶: Number of points sampled along each simulation’s thermochemical profile.

abstractmethod process_results(skip_data=False)¶: Process results, returning the metric and (optionally) sampled data.

abstractmethod run_case(restart=False)¶: Run the simulation and return its global metric.

save_file¶: Path to any intermediate data file written during the run. Simulation types that write one (e.g., autoignition) set this in setup_case; those that don’t (e.g., laminar flame) leave it None.

abstractmethod setup_case()¶: Initialize the simulation case.

class pymars.simulation.FlameSimulation(idx, properties, model, phase_name='', path='', min_flame_speed=None)¶

Class for one-dimensional freely-propagating laminar flame simulations.

Parameters:

idx (int) – Identifier index for case
properties (InputLaminarFlame) – Object with initial conditions for simulation
model (str) – Filename for Cantera-format model to be used
phase_name (str, optional) – Optional name for phase to load from YAML file (e.g., ‘gas’).
path (str, optional) – Path for location of output files

calculate()¶

Solve the flame and return only the flame speed.

Returns a flame speed of 0.0 (rather than raising) when no flame is detected – a solver failure or a degenerate, non-physical flame speed – so that a reduced model that can no longer sustain a flame is rejected through the error metric instead of aborting the reduction, mirroring how IgnitionSimulation.calculate treats a non-igniting model.

Returns:: Computed laminar flame speed in m/s, or 0.0 if no flame is detected.
Return type:: float

min_flame_speed = 0.05¶: Default minimum physically-meaningful laminar flame speed, in m/s. A solved flame speed at or below the active floor (negative or near-zero) is treated as “no flame detected” – a degenerate, non-physical result – and handled the same as a solver failure (a non-flammable mixture tends to “solve” to such a speed rather than raising). The floor can be raised or lowered per run via the min_flame_speed constructor argument (e.g., for a fuel with genuinely low flame speeds).

process_results(skip_data=False)¶

Solve the flame and sample data along the flame profile.

Uses run_case, so an undetectable flame raises RuntimeError; this path samples data for the original model, where a missing flame should halt the reduction.

Parameters:: skip_data (bool) – Flag to skip sampling thermochemical data
Returns:: Flame speed, or flame speed and sampled data
Return type:: float, or tuple of float and numpy.ndarray

run_case(restart=False)¶

Solve the laminar flame and return the unburned flame speed.

Raises RuntimeError if no flame is detected (solver failure or a degenerate, non-physical flame speed). This is the path used for the original (baseline) model, where an undetectable flame should halt the reduction rather than be silently ignored.

Parameters:: restart (bool) – Unused; retained for interface symmetry with IgnitionSimulation.
Returns:: Computed laminar flame speed in m/s
Return type:: float

setup_case()¶: Initialize simulation case.

class pymars.simulation.IgnitionSimulation(idx, properties, model, phase_name='', path='')¶

Class for ignition delay simulations

Parameters:

idx (int) – Identifer index for case
properties (InputIgnition) – Object with initial conditions for simulation
model (str) – Filename for Cantera-format model to be used
phase_name (str, optional) – Optional name for phase to load from YAML file (e.g., ‘gas’).
path (str, optional) – Path for location of output files

calculate()¶

Run simulation case, just for ignition delay.

Returns an ignition delay of 0.0 (rather than raising) when the model does not ignite or the integrator fails (e.g., a CVODES error), so a reduced candidate that can no longer be integrated is rejected through the error metric instead of aborting the reduction. This mirrors FlameSimulation.calculate and the no-flame handling (see issue #69).

Returns:: Computed ignition delay in seconds, or 0.0 if the model does not ignite or the integration fails.
Return type:: float

process_results(skip_data=False)¶

Process integration results to sample data

Parameters:: skip_data (bool) – Flag to skip sampling thermochemical data
Returns:: Ignition delay, or ignition delay and sampled data
Return type:: tuple of float, numpy.ndarray or float

run_case(stop_at_ignition=False, restart=False)¶

Run simulation case set up setup_case.

If no end time is specified for the integration, the function integrates to steady state (or a maximum of 10,000 steps, by default). This is done by checking whether the system state changes below a certain threshold, with the residual computed using feature checking. This is blatantly stolen from Cantera’s cantera.ReactorNet.advance_to_steady_state() method.

Parameters:

stop_at_ignition (bool) – If True, stop integration at ignition point, don’t save data.
restart (bool) – If True, skip if results file exists.

Returns:

self.ignition_delay – Computed ignition delay in seconds

Return type:

float

setup_case()¶: Initialize simulation case.

class pymars.simulation.PSRSimulation(idx, properties, model, phase_name='', path='')¶

Class for steady perfectly stirred reactor (PSR) simulations.

The steady temperature-vs-residence-time response curve is traced through its extinction turning point by pseudo-arclength continuation (see pymars.psr_solver). Three points are sampled from the burning branch: the extinction turning point, the point nearest a residence time of 0.1 s, and their logarithmic midpoint.

The global metric is a length-three vector [tau_ext, T_mid, T_near]: the extinction residence time, and the response temperatures at the log-midpoint and 0.1 s points. Combined element-wise by calculate_error (relative error, maximized), the error metric is the larger of the extinction residence-time error and the response-temperature errors.

Parameters:

idx (int) – Identifier index for case
properties (InputPSR) – Object with inlet conditions for the simulation
model (str) – Filename for Cantera-format model to be used
phase_name (str, optional) – Optional name for phase to load from YAML file (e.g., ‘gas’).
path (str, optional) – Path for location of output files

calculate()¶

Trace the PSR response curve and return only the metric vector.

Returns a zero metric vector (rather than raising) when no extinction curve is detected, so that a reduced model that can no longer sustain a stirred reactor is rejected through the error metric instead of aborting the reduction, mirroring how IgnitionSimulation/FlameSimulation treat a non-igniting / non-flammable model.

Returns:: Metric vector [tau_ext, T_mid, T_near], or zeros if no curve is detected.
Return type:: numpy.ndarray

num_sample_points = 3¶: Number of points sampled from the response curve (extinction turning point, nearest 0.1 s, and their log-midpoint).

process_results(skip_data=False)¶

Trace the response curve and sample the state at the three points.

Uses run_case, so a curve that cannot be traced raises RuntimeError; this path samples data for the original model, where a missing curve should halt the reduction.

Parameters:: skip_data (bool) – Flag to skip sampling thermochemical data
Returns:: Metric vector, or metric vector and sampled data of shape (num_sample_points, 2 + n_species).
Return type:: numpy.ndarray, or tuple of numpy.ndarray and numpy.ndarray

run_case(restart=False)¶

Trace the PSR response curve and return the metric vector.

Raises RuntimeError if no extinction curve is detected. This is the path used for the original (baseline) model, where a failure to trace the curve should halt the reduction rather than be silently ignored.

Parameters:: restart (bool) – Unused; retained for interface symmetry with IgnitionSimulation.
Returns:: Metric vector [tau_ext, T_mid, T_near].
Return type:: numpy.ndarray

setup_case()¶: Initialize simulation case.

simulation¶

Navigation

Related Topics