—

Elemental Balance: two complementary views.

---

bloc provides two complementary functions for inspecting elemental composition:

• compute_element_balance() – element-level view: returns the mass fraction of every element in the mixture (e.g. 74.9 % C, 25.1 % H by mass). Values sum to 1.0 over all elements. Use this when you want to know how the total mass is distributed across elements.

• compute_element_contributions() – species-level view: for each element, returns the percentage carried by every species (e.g. 80 % of C comes from C2H2, 20 % from CH4). Values sum to 100 % for each element independently. Use this when you want to know which species carry a particular element.

import cantera as ct

from bloc.balance import compute_element_balance, compute_element_contributions

Setup

Consider a CH4 dissociation mixture at 1500 K:

gas = ct.Solution("gri30.yaml")
gas.TPX = 1500, 1e5, "CH4:0.2, C2H2:0.4, H2:0.6"

Element-level view: compute_element_balance

“How is the total mass distributed across elements?”

Returns {element: mass_fraction} where values sum to 1.0 over all elements.

balance = compute_element_balance(gas, elements=["C", "H"])

print("Element balance (mass fractions, sum to 1.0 over elements):")
for elem, frac in balance.items():
    print(f"  {elem}: {frac:.4f}  ({frac:.1%} of total mass)")

total = sum(balance.values())
print(f"  Sum = {total:.4f}")

Species-level view: compute_element_contributions

“For a given element, which species carry it?”

Returns {element: {species: percentage}} where percentages sum to 100 % for each element independently.

contributions = compute_element_contributions(gas, elements=["C", "H"])

print("\nCarbon contributions (sum to 100% for C):")
for species, percentage in contributions["C"].items():
    print(f"  {species}: {percentage:.1f}%")

print("\nHydrogen contributions (sum to 100% for H):")
for species, percentage in contributions["H"].items():
    print(f"  {species}: {percentage:.1f}%")