bloc.cfd_pathlines.chemistry#

Cantera chemistry replay along CFD prescribed temperature-time histories.

Each CFD pathline provides a Lagrangian T(t) trajectory. ChemistryReplay integrates the chemical kinetics at constant pressure along that trajectory using a piece-wise constant temperature approximation: within each CFD step interval the temperature is held at the CFD value at the start of the interval and the species evolve freely under the kinetics.

This lets you: - Validate the CFD mechanism by comparing replayed species to CFD species. - Compare multiple mechanisms driven by the same T(t) history.

Classes#

ChemistryReplay

Replay chemical kinetics along CFD temperature-time histories.

Functions#

compare_mechanisms(dataset, mechanisms, species[, ...])

Run multiple mechanism replays and compare them against CFD.

Module Contents#

class bloc.cfd_pathlines.chemistry.ChemistryReplay(dataset, mechanism, label='')#

Replay chemical kinetics along CFD temperature-time histories.

Parameters:

  • dataset – Loaded pathline dataset. The initial species composition at step=0 of each path is used as the inlet condition.

  • mechanism – Path to a Cantera YAML mechanism file.

  • label – Human-readable label for this replay (used in plots).

Raises:

FileNotFoundError – If the mechanism file does not exist.

label#
run()#

Integrate kinetics for every path.

The Cantera Solution, Reactor, and ReactorNet are created once and reused across all paths — only the gas state is reset between paths, avoiding repeated mechanism parsing and preconditioner setup.

Returns:

Per-path DataFrames with columns time_s, T_K, and X_<species> for every species in the mechanism.

Return type:

dict[int, pd.DataFrame]

classmethod from_csv(dataset, mechanism, csv_dir, label='')#

Load replay results from previously saved CSV files instead of running.

Expects one path_{pid}.csv file per path in csv_dir, as written by save_results().

Parameters:

  • dataset – The pathline dataset this replay belongs to (used for metadata).

  • mechanism – Path to the Cantera mechanism file (used for labelling and species lookup in plots).

  • csv_dir – Directory containing the path_{pid}.csv files.

  • label – Human-readable label. Defaults to the mechanism stem.

Returns:

Instance with results already populated — no need to call run().

Return type:

ChemistryReplay

Raises:

FileNotFoundError – If csv_dir does not exist or contains no path_*.csv files.

save_results(output_dir)#

Write per-path replay results to CSV files.

One file per path, named path_{pid}.csv, placed in output_dir (created if it does not exist). Each file has the same columns as the DataFrames returned by run(): time_s, T_K, and X_<species> for every species in the mechanism.

Parameters:

output_dir – Directory to write CSV files into.

Returns:

Paths of the written files, sorted by path id.

Return type:

list[Path]

Raises:

RuntimeError – If run() has not been called yet.

property results: dict[int, pandas.DataFrame]#

Replay results; call run() first.

Raises:

RuntimeError – If run() has not been called yet.

plot_species_comparison(cfd_dataset, species, path_ids=None, figsize=None)#

Plot CFD mole fractions vs. replayed mole fractions per species.

Each path gets a distinct color from the tab20 colormap. CFD curves use solid lines; replay curves use dashed lines. One subplot per species.

Parameters:

  • cfd_dataset – The source pathline dataset (CFD values).

  • species – Species names to compare (Cantera names, no X_ prefix).

  • path_ids – Subset of path ids to include. Defaults to all.

  • figsize – Figure size override.

Raises:

RuntimeError – If run() has not been called yet.

bloc.cfd_pathlines.chemistry.compare_mechanisms(dataset, mechanisms, species, path_ids=None, compare_CFD=True, sum_bin_comparison=False)#

Run multiple mechanism replays and compare them against CFD.

Each path gets a distinct color. CFD uses solid lines; each mechanism gets the next linestyle in the sequence (--, -., …).

Parameters:

  • dataset – Source pathline dataset (also supplies CFD values for comparison).

  • mechanisms – Either a {label: mechanism_path} mapping (replays are run here) or a list of already-run ChemistryReplay objects (no re-run).

  • species – Species to plot (Cantera names, no X_ prefix).

  • path_ids – Subset of paths to include. Defaults to all.

  • compare_CFD – Overlay CFD curves alongside the mechanism replays. Defaults to True.

  • sum_bin_comparison – Append an extra subplot showing sum(X_BIN*) for each source. Useful for comparing total soot precursor/particle loading across mechanisms. The BIN species summed are those whose column names start with X_BIN in the replay results (or in the CFD dataset when compare_CFD is True).

Returns:

One subplot per species, plus one sum(BIN) subplot when sum_bin_comparison=True.

Return type:

plt.Figure