bloc.plotting#

Plotting helpers for reactor time-series and Sankey diagrams.

Submodules#

Attributes#

color_H2

color_Cs

color_CH4

color_others

color_hhv_others

SPECIES_COLORS

SOLID_LINESTYLES

OTHER_LINESTYLE

SPECIES_COLORS

color_CH4

color_Cs

color_H2

color_hhv_others

color_others

color_mass

Functions#

resolve_n_c_min([gas, config, mechanism, warn_on_guess])

Resolve the solid-carbon criterion to use, in order of precedence.

get_solid_carbon_species(gas[, n_C_min, ...])

Return a list of solid carbon species from the gas phase object.

plot_speciesPie(gas[, quantity, thresh])

Plot a pie chart of the species composition of a Cantera gas object.

get_top_species_by_mole(states[, n])

Return top-N species names by final mole fraction from a states object.

get_top_species_by_mass(states[, n])

Return top-N species names by final mass fraction from a states object.

plot_simu_vs_t(states[, quantity, s_to_plot, xscale, ...])

Plot the temperature and composition as a function of time starting from a Cantera states object.

plot_simu_vs_x(states, qm, S[, quantity, s_to_plot, ...])

plot_psr_temperature_vs_t(states[, xscale, xmin, ...])

Plot PSR temperature as a function of time.

plot_psr_composition_vs_t(states[, s_to_plot, ...])

Plot PSR composition as a function of time.

plot_pfr_composition_dual_axis(states, qm, S[, ...])

Plot PFR composition with dual x-axes (time and distance), linear scale.

plot_pfr_temperature_dual_axis(states, qm, S[, save_path])

Plot PFR temperature with dual x-axes (time and distance), linear scale.

plot_pfr_composition_dual_axis_log(states, qm, S[, ...])

Plot PFR composition with dual x-axes (time and distance), log scale.

plot_pfr_temperature_dual_axis_log(states, qm, S[, ...])

Plot PFR temperature with dual x-axes (time and distance), log scale.

collect_all_reactors_and_reservoirs(sim)

Collect all Reactors and Reservoirs in a Network.

resolve_n_c_min([gas, config, mechanism, warn_on_guess])

Resolve the solid-carbon criterion to use, in order of precedence.

get_solid_carbon_species(gas[, n_C_min, ...])

Return a list of solid carbon species from the gas phase object.

get_upstream_nodes(links, nodes, node_name)

List names of upstream nodes of a given node.

get_downstream_nodes(links, nodes, node_name)

List all outlets of a node.

get_inlet_value(links, nodes, node_name[, ...])

Get the sum of all inlet streams of a node.

get_outlet_value(links, nodes, node_name[, ...])

Get the sum of all outlet streams of a node.

print_links(links, nodes)

Print the links in a readable format.

add_link(links, nodes, source_str, target_str, value)

Add a connection between Source and Target.

add_node(nodes, node_str[, color])

substract_value(links, nodes, source_str, target_str, ...)

Substract a value from a link.

safe_print(msg)

Print a message, safely handling Unicode characters on Windows.

plot_sankey_diagram(sim)

Plot Sankey Diagram for a simulation.

plot_sankey_diagram_from_links_and_nodes(links, nodes)

Plot Sankey Diagram from links and nodes.

generate_sankey_input_from_sim(sim[, node_order, ...])

Generate input data for sankey plot from a Cantera Reactor Net simulation.

Package Contents#

bloc.plotting.resolve_n_c_min(gas=None, *, config=None, mechanism=None, warn_on_guess=True)#

Resolve the solid-carbon criterion to use, in order of precedence.

  1. An explicit settings.get_carbon_yield.n_C_min in config (dict-like or attrs-style) always wins – an engineer’s deliberate override.

  2. A registry hit by mechanism basename (mechanism, or gas.source).

  3. auto_n_c_min()’s single conservative fallback, loudly warned as an unvalidated guess – covers both an unregistered mechanism and a call with nothing to resolve against at all.

Parameters:

  • gas – A live Cantera Solution/SolutionArray to classify, if one is already built (avoids constructing one just to resolve a threshold).

  • config – A STONE config (dict or attrs-style) that may declare settings.get_carbon_yield.n_C_min.

  • mechanism – A bare mechanism name/path, used for registry lookup when gas isn’t available yet, or as a fallback identity when gas is given but its own .source doesn’t resolve to a recognized basename.

  • warn_on_guess – Passed through to auto_n_c_min(); set False to silence the “unvalidated guess” warning (e.g. in a tight loop that already warned once).

Return type:

NCMinResult

Examples

See PAH size-dependent melting vs. mechanism solid-carbon thresholds., which overlays every registered mechanism’s resolved n_C_min against a PAH melting-point-vs-size phase diagram.

bloc.plotting.get_solid_carbon_species(gas, n_C_min=80, solid_species_base=['C(s)', 'C(soot)', 'CSOLID', 'C(gr)'], return_indices=False)#

Return a list of solid carbon species from the gas phase object.

Parameters:

  • gas (cantera.Solution or cantera.SolutionArray) – The solution object from Cantera.

  • n_C_min (int or None, optional) – Minimum number of carbon atoms to consider a species as solid. Default is 80, according to Martin et al., PR#182 (spark-cleantech-l3/bloc#182). None means “no count-based rule at all” – only solid_species_base marks a species as solid (see bloc.chem.solid_carbon_threshold.resolve_n_c_min(), which returns None for mechanisms with no PAH/soot continuum, e.g. Fincke_GRC).

  • solid_species_base (list of str, optional) – Predefined list of solid species names. Default is ["C(s)", "C(soot)", "CSOLID", "C(gr)"].

  • return_indices (bool, optional) – If True, return each solid species’ index into gas.species_names (int) instead of its name (str). Default False. Useful for callers that repeatedly index a state array (e.g. phase.Y[indices]) and would otherwise need a second pass through cantera.Solution.species_index() to convert names to indices.

Returns:

solid_species – Names (default) or indices (return_indices=True) of species that have at least n_C_min carbon atoms OR are in the predefined solid species list.

Return type:

list of str or list of int

bloc.plotting.color_H2 = '#B481FF'#
bloc.plotting.color_Cs = '#000000'#
bloc.plotting.color_CH4 = '#E63946'#
bloc.plotting.color_others = '#607D8B'#
bloc.plotting.color_hhv_others = '#8B0000'#
bloc.plotting.SPECIES_COLORS#
bloc.plotting.SOLID_LINESTYLES = ['-', '--', '-.']#
bloc.plotting.OTHER_LINESTYLE = ':'#
bloc.plotting.plot_speciesPie(gas, quantity='mole', thresh=0.005)#

Plot a pie chart of the species composition of a Cantera gas object.

FIgure is displayed in an Excel sheet

bloc.plotting.get_top_species_by_mole(states, n=8)#

Return top-N species names by final mole fraction from a states object.

Parameters:

  • states (SolutionArray) – Cantera time-series states object.

  • n (int) – Maximum number of species to return.

Returns:

Species names sorted by descending final mole fraction, capped at n.

Return type:

list of str

bloc.plotting.get_top_species_by_mass(states, n=8)#

Return top-N species names by final mass fraction from a states object.

Parameters:

  • states (SolutionArray) – Cantera time-series states object.

  • n (int) – Maximum number of species to return.

Returns:

Species names sorted by descending final mass fraction, capped at n.

Return type:

list of str

bloc.plotting.plot_simu_vs_t(states, quantity='mole', s_to_plot=None, xscale='log', yscale='linear', xmin=0, xmax=None, n_sheet=1, save=False, save_name=None)#

Plot the temperature and composition as a function of time starting from a Cantera states object.

The figure is displayed in an Excel sheet.

bloc.plotting.plot_simu_vs_x(states, qm, S, quantity='mole', s_to_plot=None, xscale='log', yscale='linear', xmin=0, xmax=None, n_sheet=1, save=False, save_name=None)#
bloc.plotting.plot_psr_temperature_vs_t(states, xscale='log', xmin=0, xmax=None, save=False, save_name=None)#

Plot PSR temperature as a function of time.

Parameters:

  • states (SolutionArray) – PSR reactor states (time-series).

  • xscale (str) – “log” or “linear” scale for x-axis.

  • xmin (float or None) – X-axis limits.

  • xmax (float or None) – X-axis limits.

  • save (bool) – If True, save figure to file.

  • save_name (str or None) – Base name for saving (without extension).

Returns:

Path to saved figure, or None if not saved.

Return type:

str or None

bloc.plotting.plot_psr_composition_vs_t(states, s_to_plot=None, quantity='mole', xscale='log', yscale='linear', xmin=0, xmax=None, save=False, save_name=None)#

Plot PSR composition as a function of time.

Parameters:

  • states (SolutionArray) – PSR reactor states (time-series).

  • s_to_plot (list of str or None) – Species to plot. If None, top 8 by final mole or mass fraction.

  • quantity (str) – “mole” or “mass” fraction.

  • xscale (str) – “log” or “linear” scale for x-axis.

  • yscale (str) – “log” or “linear” scale for y-axis.

  • xmin (float or None) – X-axis limits.

  • xmax (float or None) – X-axis limits.

  • save (bool) – If True, save figure to file.

  • save_name (str or None) – Base name for saving (without extension).

Returns:

Path to saved figure, or None if not saved.

Return type:

str or None

bloc.plotting.plot_pfr_composition_dual_axis(states, qm, S, s_to_plot=None, save_path=None, quantity='mole')#

Plot PFR composition with dual x-axes (time and distance), linear scale.

Parameters:

  • states (SolutionArray) – PFR reactor states (time-series).

  • qm (float) – Total mass flow rate in kg/s.

  • S (float) – Reactor cross-section area in m2.

  • s_to_plot (list of str or None) – Species to plot. If None, top 8 by final mole or mass fraction.

  • save_path (str or None) – If provided, save figure to this path (PNG).

  • quantity (str) – "mole" or "mass".

Returns:

Path to saved figure, or None if not saved.

Return type:

str or None

bloc.plotting.plot_pfr_temperature_dual_axis(states, qm, S, save_path=None)#

Plot PFR temperature with dual x-axes (time and distance), linear scale.

bloc.plotting.plot_pfr_composition_dual_axis_log(states, qm, S, s_to_plot=None, save_path=None, quantity='mole')#

Plot PFR composition with dual x-axes (time and distance), log scale.

bloc.plotting.plot_pfr_temperature_dual_axis_log(states, qm, S, save_path=None)#

Plot PFR temperature with dual x-axes (time and distance), log scale.

bloc.plotting.collect_all_reactors_and_reservoirs(sim)#

Collect all Reactors and Reservoirs in a Network.

Parameters:

sim (cantera.ReactorNet)

Return type:

set of cantera.Reactor

bloc.plotting.resolve_n_c_min(gas=None, *, config=None, mechanism=None, warn_on_guess=True)#

Resolve the solid-carbon criterion to use, in order of precedence.

  1. An explicit settings.get_carbon_yield.n_C_min in config (dict-like or attrs-style) always wins – an engineer’s deliberate override.

  2. A registry hit by mechanism basename (mechanism, or gas.source).

  3. auto_n_c_min()’s single conservative fallback, loudly warned as an unvalidated guess – covers both an unregistered mechanism and a call with nothing to resolve against at all.

Parameters:

  • gas – A live Cantera Solution/SolutionArray to classify, if one is already built (avoids constructing one just to resolve a threshold).

  • config – A STONE config (dict or attrs-style) that may declare settings.get_carbon_yield.n_C_min.

  • mechanism – A bare mechanism name/path, used for registry lookup when gas isn’t available yet, or as a fallback identity when gas is given but its own .source doesn’t resolve to a recognized basename.

  • warn_on_guess – Passed through to auto_n_c_min(); set False to silence the “unvalidated guess” warning (e.g. in a tight loop that already warned once).

Return type:

NCMinResult

Examples

See PAH size-dependent melting vs. mechanism solid-carbon thresholds., which overlays every registered mechanism’s resolved n_C_min against a PAH melting-point-vs-size phase diagram.

bloc.plotting.get_solid_carbon_species(gas, n_C_min=80, solid_species_base=['C(s)', 'C(soot)', 'CSOLID', 'C(gr)'], return_indices=False)#

Return a list of solid carbon species from the gas phase object.

Parameters:

  • gas (cantera.Solution or cantera.SolutionArray) – The solution object from Cantera.

  • n_C_min (int or None, optional) – Minimum number of carbon atoms to consider a species as solid. Default is 80, according to Martin et al., PR#182 (spark-cleantech-l3/bloc#182). None means “no count-based rule at all” – only solid_species_base marks a species as solid (see bloc.chem.solid_carbon_threshold.resolve_n_c_min(), which returns None for mechanisms with no PAH/soot continuum, e.g. Fincke_GRC).

  • solid_species_base (list of str, optional) – Predefined list of solid species names. Default is ["C(s)", "C(soot)", "CSOLID", "C(gr)"].

  • return_indices (bool, optional) – If True, return each solid species’ index into gas.species_names (int) instead of its name (str). Default False. Useful for callers that repeatedly index a state array (e.g. phase.Y[indices]) and would otherwise need a second pass through cantera.Solution.species_index() to convert names to indices.

Returns:

solid_species – Names (default) or indices (return_indices=True) of species that have at least n_C_min carbon atoms OR are in the predefined solid species list.

Return type:

list of str or list of int

bloc.plotting.SPECIES_COLORS#
bloc.plotting.color_CH4 = '#E63946'#
bloc.plotting.color_Cs = '#000000'#
bloc.plotting.color_H2 = '#B481FF'#
bloc.plotting.color_hhv_others = '#8B0000'#
bloc.plotting.color_others = '#607D8B'#
bloc.plotting.get_upstream_nodes(links, nodes, node_name)#

List names of upstream nodes of a given node.

Parameters:

  • links (dict) – Network links. Dictionary with keys {‘source’, ‘target’, ‘value’, ‘color’, ‘label’}

  • nodes (list) – Network list of names of nodes.

  • node_name (str) – Name of the node.

Returns:

List of upstream nodes of the node.

Return type:

list of str

bloc.plotting.get_downstream_nodes(links, nodes, node_name)#

List all outlets of a node.

bloc.plotting.get_inlet_value(links, nodes, node_name, filter_links='', get_color=False)#

Get the sum of all inlet streams of a node.

bloc.plotting.get_outlet_value(links, nodes, node_name, filter_links='', get_color=False)#

Get the sum of all outlet streams of a node.

Print the links in a readable format.

Add a connection between Source and Target.

bloc.plotting.add_node(nodes, node_str, color=None)#
bloc.plotting.substract_value(links, nodes, source_str, target_str, value, link_name=None, allow_negative=False)#

Substract a value from a link.

bloc.plotting.color_mass = '#EBE2F6'#
bloc.plotting.safe_print(msg)#

Print a message, safely handling Unicode characters on Windows.

bloc.plotting.plot_sankey_diagram(sim)#

Plot Sankey Diagram for a simulation.

Show the figure by default. If you want the figure without showing it, use plot_sankey_diagram_from_links_and_nodes().

Parameters:

sim (Cantera ReactorNet object) – A ReactorNet instance containing a list of reactors; already resolved.

Example

sim.advance_to_steady_state()
plot_sankey_diagram(sim)

See also

generate_sankey_input_from_sim(), plot_sankey_diagram_from_links_and_nodes()

Plot Sankey Diagram from links and nodes.

Note: Physical nodes should already have circled-number prefixes applied to their names before calling this function.

Parameters:

  • links (dict) – Dictionary containing the links for the sankey diagram.

  • nodes (list) – List of nodes for the sankey diagram.

  • show (bool) – Whether to show the plot or not. Default is False.

Returns:

The Sankey diagram.

Return type:

plotly.graph_objects.Figure

bloc.plotting.generate_sankey_input_from_sim(sim, node_order=[], exclude_nodes=None, flow_type='hhv', show_species=['H2', 'CH4', 'C(s)'], if_no_species='raise', verbose=False, **kwargs)#

Generate input data for sankey plot from a Cantera Reactor Net simulation.

Parameters:

  • sim (Cantera ReactorNet object) – A ReactorNet instance containing a list of reactors.

  • node_order (list of str) – Order for the nodes in the sankey diagram (optional). In case no order is passed, a generic order will be used.

  • flow_type (str) – Type of flow to be considered in the sankey diagram. Default is “hhv”. # TODO : implement other types of flow (e.g. “enthalpy”, “exergy”, etc.)

  • show_species (list of (str, or list-of-str) elements) –

    List of species to show in the sankey diagram. Default is [“H2”, “C(s)”]. Set to [] not to show any species. If a list-of-str is given, these species names are merged together and given the name of the first one. Ex:

    show_species = ["H2", "CH4", ["C(s)", "C(soot)", "BIN25"]]

  • if_no_species ("raise", "ignore") – what to do if one of the species in show_species list is absent in at least one of the reactors of the ReactorNet: raise an error, or ignore it.

  • verbose (bool) – if True, print details about Sankey network generation.

Returns:

Tuple containing the links and node_order for the plotly sankey diagram.

Return type:

tuple

Example

links, nodes = generate_sankey_input_from_sim(sim)

import plotly.graph_objects as go

fig = go.Figure(go.Sankey(
    arrangement='snap',
    node={
        'label': nodes,
        'pad':11,
        'color': 'orange'
    },
    link=links
))
fig.show()

See also

plot_sankey_diagram()