Convergence history

Convergence history tracking for the time-stepping loop.

Stores a 1D time-series of stagnation conditions, residuals, and CFL numbers at inlet and outlet for convergence monitoring and post-processing.

class ember.convergence_history.ConvergenceHistory(shape=())

Allocate the data array.

Parameters:

shape (tuple) – Shape of a single property array.

classmethod from_grid(n_step, grid)

Initialize convergence history from grid.

Parameters:

• n_step (int) – Number of time steps to allocate

• grid (Grid) – Grid object containing blocks with patches

Returns:

Configured instance ready to record data

Return type:

ConvergenceHistory

classmethod from_ts3(filename, grid)

Reconstruct a ConvergenceHistory from a TS3 text log file.

The per-step history (residuals, mass flows, stagnation conditions) is parsed from the log; the reference scales needed to non-dimensionalize it (areas, V_ref, T_ref, node count) are derived from grid, which the log does not record. The fluid is taken from the log header, the authoritative record of what TS3 actually ran with.

Parameters:

• filename (str) – Path to TS3 log file (e.g. log_duct.txt)

• grid (ember.grid.Grid) – The grid that was solved, for reference scales (V_ref, T_ref, areas).

Return type:

ConvergenceHistory

classmethod read_cnv(filename)

Read convergence history from CNV binary format file.

Automatically detects gzip-compressed files.

Parameters:

filename (str) – Input CNV file to read

Return type:

ConvergenceHistory

format_message(i_finest=None, n_step=None, n_levels=None, show_cfl=True)

Format convergence message for current log step.

Parameters:

• i_finest (int, optional) – When provided, a timing line is inserted after the step header.

• n_step (int, optional) – When provided, a timing line is inserted after the step header.

• n_levels (int, optional) – When provided, a timing line is inserted after the step header.

• show_cfl (bool, optional) – Append the per-equation CFL line (default True). Set False for fixed-CFL marches (e.g. the explicit scree loop) that never populate now.cfl.

Returns:

Formatted convergence status message

Return type:

str

format_timing(i_step, i_finest, n_step, n_levels)

Format timing line: tpnps at current level, elapsed, and estimated remaining.

Parameters:

• i_step (int) – Current global step index

• i_finest (int) – Index of the finest currently active grid level (0 = finest)

• n_step (int) – Steps per FMG phase (conf.n_step); equals total steps when no FMG

• n_levels (int) – Total number of multigrid levels (conf.n_levels)

record_convergence(conv)

Record the per-step convergence monitors at the current log step.

Parameters:

conv (ember.grid.Convergence) – Namedtuple from ember.grid.Grid.get_convergence(). residual has shape (5,); mdot, ho, s are (2*n_row,) non-dimensional station vectors [row0_up, row0_dn, row1_up, row1_dn, ...]; the remaining scalar fields carry the outlet throttle state (mdot_target, mdot_throttle, P_throttle, dP_P, dP_I, dP_D).

record_step(i_step)

Record a new step in the history.

Parameters:

i_step (int) – The step index to record

Returns:

The log index where this step was recorded

Return type:

int

to_json(directory='.')

Write convergence history to three JSON files in directory.

Writes err_mdot.json, work.json, and convergence_loss.json, each containing a list of {“x”: i_step, “y”: value} objects.

Parameters:

directory (str or path-like, optional) – Output directory (default current directory).

write_cnv(filename, compress=False)

Write convergence history to CNV binary format file.

Parameters:

• filename (str) – Output filename

• compress (bool, optional) – If True, compress using gzip (default False)

property A_in

Total inlet area [m^2].

property A_out

Total outlet area [m^2].

property cfl

CFL numbers for conserved variables [shape (…, 5)].

property dP_D

Derivative PID contribution [Pa].

property dP_I

Integral PID contribution [Pa].

property dP_P

Proportional PID contribution [Pa].

property err_mdot

Mass flow rate error at each logged step.

property err_mdot_row

Per-row mass flow conservation error, shape (n_log, n_row).

err[i, r] = (mdot_dn_r - mdot_up_r) / mdot_avg_r

Returns NaN array if n_row metadata is absent (old histories).

property ho

Non-dimensional stagnation enthalpy at each station [shape (…, 2*n_row)].

property ho_in

Inlet non-dimensional specific stagnation enthalpy (first station).

Non-dimensionalised by u_ref. Carries an offset dependent on the arbitrary datum where \(u = s = 0\) at \((p_\mathrm{dtm}, T_\mathrm{dtm})\); only changes are physically meaningful. See Datum state.

property ho_out

Outlet non-dimensional specific stagnation enthalpy (last station).

Non-dimensionalised by u_ref. Carries an offset dependent on the arbitrary datum where \(u = s = 0\) at \((p_\mathrm{dtm}, T_\mathrm{dtm})\); only changes are physically meaningful. See Datum state.

property i_log

Current log index (-1 means no steps recorded yet).

property i_step

Step index counter.

property mdot

Non-dimensional mass flow at each station [shape (…, 2*n_row)].

property mdot_in

Inlet non-dimensional mass flow (first station).

property mdot_out

Outlet non-dimensional mass flow (last station).

property mdot_target

Throttle setpoint [kg/s]; 0 = inactive.

property mdot_throttle

Actual mdot at outlet [kg/s].

property n_node

Total number of nodes in the grid.

property now

View of the current step (at i_log position).

property P_throttle

Pressure on throttle curve [Pa].

property psi

Non-dimensional stagnation-enthalpy rise, ho_out - ho_in.

Both terms are already non-dimensional (scaled by u_ref), so this is the inlet-to-outlet stagnation enthalpy change on the fluid reference scale – no separate kinetic-energy normalisation.

property residual

Residuals for conserved variables [shape (…, 5)].

property s

Non-dimensional specific entropy at each station [shape (…, 2*n_row)].

property s_in

Inlet non-dimensional specific entropy (first station).

property s_out

Outlet non-dimensional specific entropy (last station).

property throttle

Throttle state [shape (n_step, 3)].

property time

Elapsed time [units of _TIME_SCALE seconds].

property tpnps

Time per node per step [\(\mu\mathrm{s}\)], from the last recorded interval.

property zeta

Non-dimensional entropy rise, s_out - s_in.

Both terms are already non-dimensional (scaled by Rgas_ref), so this is the inlet-to-outlet entropy generation on the fluid reference scale. It remains positive for an irreversible process (Gouy-Stodola), but is no longer normalised by a reference kinetic energy.