A batch-weight calculator for solid-state ceramic synthesis. Give it a target composition and a batch mass, and it tells you how many grams of each raw material to weigh out. Every run is appended to an Excel log workbook, so nothing already recorded is ever overwritten.
Written and maintained by Amir Khesro, University of Sheffield.
A computer with Python 3.11 or newer. To check, open a terminal (see step 1 below) and run:
python --version
If Python is missing or too old, install it from https://www.python.org/downloads/ and tick the box that says "Add Python to PATH" during installation.
On Windows, press the Start key, type "PowerShell" and press Enter. On macOS, open the Terminal app. On Linux, open your usual terminal.
Do not run PowerShell as administrator. It is not needed and it starts you in a protected system folder where the log file cannot be written.
Copy this line into the terminal and press Enter:
pip install batchcalc
batchcalc --version
You should see a version number, for example batchcalc 0.2.0. If PowerShell
says the command is not recognised, close the terminal, open a new one and try
again. If it still fails, run it as python -m batch_calculations.cli --version
and use that form throughout.
The Excel log is written to whatever folder the terminal is currently in, so go somewhere sensible first:
cd $HOME\Documents
The pattern is: composition in quotes, then batch mass in grams.
batchcalc "Ba0.85Ca0.15Zr0.1Ti0.9O3" 30
You get the formula weight, the moles of product, and a weighing table listing
grams of each raw material, the total mass to weigh, and the mass that will be
lost on firing as CO2. The run is also appended to stoichiometry_log.xlsx
in the current folder.
Read the assay from each bottle and pass it as a fraction, one flag per reagent:
batchcalc "Ba0.85Ca0.15Zr0.1Ti0.9O3" 30 --purity BaCO3=0.995 --purity TiO2=0.999
The calculator weighs those reagents proportionally heavier so that the moles of cation delivered are exactly right. Enter purities for any batch that will be measured, compared or published. It is the differences in purity between reagents that shift your cation ratios, not the absolute values, so a purity common to every bottle changes nothing while a mismatch between two bottles shifts stoichiometry by roughly the size of the mismatch.
Choose a different raw material for an element (defaults are carbonates for alkalis and alkaline earths, oxides for most other cations):
batchcalc "BaTiO3" 10 --use Ba=BaO
Store processing notes with the batch record:
batchcalc "BaTiO3" 10 --note "calcine 1200 C, 4 h"
Quick check without saving anything:
batchcalc "BaTiO3" 10 --no-log
Send the log to a specific file:
batchcalc "BaTiO3" 10 --log C:\Users\you\Documents\my_log.xlsx
Assume a single purity for every reagent you have not named individually (the default is 1.0, meaning everything is treated as 100 per cent pure):
batchcalc "BaTiO3" 10 --default-purity 0.99
Decimal subscripts, brackets and hydrate notation are all accepted:
Ba0.5Sr0.5TiO3, La(OH)3, CuSO4*5H2O. Spaces are ignored. Write hydrates
with * or a middot, not a bare dot. Be careful to type the letter O for
oxygen, not the digit zero.
All precursors are treated as dry, with no water of crystallisation. Impurities are assumed inert: the purity correction fixes the moles of cation delivered, and the impurity mass simply ends up in the batch. Oxygen, carbon, hydrogen and nitrogen are supplied by the precursors or the furnace atmosphere and never need a raw material of their own. Reagents are taken as 100 per cent pure unless stated, so batches stay comparable run to run. The calculator cross-checks what the chosen reagents deliver against what the formula wants and prints a warning for anything missing, over-supplied or under-supplied.
Each run appends one row to a "Batches" sheet and one row per raw material to a "Raw Materials" sheet, with a shared batch ID, a timestamp, and the purities used. If the workbook is open in Excel and locked, the run is saved to a timestamped fallback file instead and the message tells you where.
"Permission denied" when saving the log: your terminal is in a protected
folder, usually C:\WINDOWS\system32. Run cd $HOME\Documents and try again.
"batchcalc is not recognised": open a fresh terminal, or use
python -m batch_calculations.cli instead.
"No default raw material for X": the element has no default precursor in the
built-in table. Tell the calculator what to use, for example --use X=XO2.
When the code improves, update with:
pip install --upgrade batchcalc
from batch_calculations import calculate_batch, print_report, append_to_log
batch = calculate_batch(
"Ba0.85Ca0.15Zr0.1Ti0.9O3",
target_mass_g=30.0,
purities={"BaCO3": 0.995, "CaCO3": 0.990},
)
print_report(batch)
append_to_log(batch, "stoichiometry_log.xlsx")
calculate_batch returns a Batch dataclass carrying the parsed composition,
formula weight, moles of product, and one Reagent per raw material with its
molar mass, purity and mass to weigh.
Pass precursor_choices to pick the raw material for an element, the Python
equivalent of --use. The defaults are defined in batch_calculations/data.py.
uv sync
uv run pytest
uv run ruff check .
Or, without uv, pip install -e . installs the package in editable form and
pytest and ruff check . then run directly.
The test suite includes batches verified against independent hand calculations.
Questions, problems and suggestions are welcome on GitHub Issues: https://github.com/amirkhesro/Batch-Calculations/issues
If a calculation looks wrong, please include the exact command you ran and the output you got.
MIT. See the LICENSE file.