Metadata-Version: 2.4
Name: balance-rxns
Version: 0.1.0
Summary: A Python package for balancing chemical equations and finding possible reactions
Project-URL: Homepage, https://github.com/muxkin/balance-rxns
Project-URL: Repository, https://github.com/muxkin/balance-rxns
Project-URL: Issues, https://github.com/muxkin/balance-rxns/issues
Author-email: Muxkin <muxkin@foxmail.com>
License: MIT
License-File: LICENSE
Keywords: balancing,chemical equations,chemistry,pymatgen,reactions
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
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.9
Requires-Dist: pymatgen>=2024.1.0
Requires-Dist: sympy>=1.12.0
Description-Content-Type: text/markdown

# balance-rxns

A Python package for balancing chemical equations and finding possible reactions.

[中文文档](README_zh.md)

## Installation

```bash
pip install balance-rxns
```

## Features

- Automatically balance chemical equations
- Find all possible reactions from given reactants and products
- Support for complex chemical formulas
- Accurate calculations based on sympy and pymatgen

## Usage

### Basic Usage

```python
from balance_rxns import balance_rxns

# Define reactants and products
reactants = ("Fe", "O2")
products = ("FeO", "Fe2O3", "Fe3O4")

# Find all possible balanced equations
results = balance_rxns(reactants, products)

# Print results
for equation, reactant_coeffs, product_coeffs in results:
    print(equation)
```

Output:
```
2Fe + O2 -> 2FeO
4Fe + 3O2 -> 2Fe2O3
3Fe + 2O2 -> Fe3O4
```

### Advanced Options

```python
# Limit the number of products
results = balance_rxns(
    reactants=["Cu", "Al2O3"],
    products=["CuAlO2"],
    max_products_in_equation=2,  # Maximum 2 products per equation
    require_all_reactants_used=True  # Require all reactants to be used
)

for equation, r_map, p_map in results:
    print(f"Equation: {equation}")
    print(f"Reactant coefficients: {r_map}")
    print(f"Product coefficients: {p_map}")
    print()
```

## Parameters

- `reactants`: List or tuple of reactant chemical formulas
- `products`: List or tuple of product chemical formulas
- `max_products_in_equation`: Maximum number of products in each equation (default: all)
- `require_all_reactants_used`: Whether all reactants must be used (default: True)

## Return Value

Returns a list where each element contains:
1. String representation of the balanced equation
2. Dictionary of reactants with their coefficients
3. Dictionary of products with their coefficients

## Dependencies

- pymatgen >= 2024.1.0
- sympy >= 1.12.0

## License

MIT License

## Contributing

Issues and Pull Requests are welcome!

## Changelog

### 0.1.0 (2026-01-30)
- Initial release
- Support for chemical equation balancing
