Metadata-Version: 2.5
Name: batchcalc
Version: 0.2.0
Summary: Stoichiometry and batch-weight calculations for solid-state ceramic synthesis.
Project-URL: Homepage, https://github.com/amirkhesro/Batch-Calculations
Project-URL: Documentation, https://github.com/amirkhesro/Batch-Calculations#readme
Project-URL: Issues, https://github.com/amirkhesro/Batch-Calculations/issues
Project-URL: Changelog, https://github.com/amirkhesro/Batch-Calculations/blob/main/CHANGELOG.md
Author-email: Amir Khesro <am.khesro@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: batch calculation,ceramics,solid-state synthesis,stoichiometry
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.11
Requires-Dist: openpyxl
Description-Content-Type: text/markdown

# batch-calculations

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.

## What you need before starting

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.

## Step 1: Open a terminal

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.

## Step 2: Install the package (once per computer)

Copy this line into the terminal and press Enter:

    pip install batchcalc

## Step 3: Check it works

    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.

## Step 4: Move to a folder where you keep lab records

The Excel log is written to whatever folder the terminal is currently in, so
go somewhere sensible first:

    cd $HOME\Documents

## Step 5: Run your first calculation

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.

## Step 6: Enter the purity of your reagents

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.

## Step 7: Other options you will use

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

## Writing formulas

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.

## Assumptions

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.

## The log workbook

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.

## Troubleshooting

"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`.

## Updating

When the code improves, update with:

    pip install --upgrade batchcalc

## Use from Python

    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`.

## Development

    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.

## Feedback and bug reports

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.

## Licence

MIT. See the LICENSE file.
