Metadata-Version: 2.2
Name: chargefw
Version: 0.1.3
Summary: Empirical partial atomic charge calculation framework
Author: ChargeFW contributors
License: MIT
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Chemistry
Project-URL: Documentation, https://github.com/krab1k/chargefw/blob/main/docs/PYTHON.md
Project-URL: Examples, https://github.com/krab1k/chargefw/tree/main/docs/recipes
Project-URL: Repository, https://github.com/krab1k/chargefw
Requires-Python: >=3.10
Requires-Dist: numpy>=1.26
Provides-Extra: gemmi
Requires-Dist: gemmi==0.7.4; extra == "gemmi"
Provides-Extra: rdkit
Requires-Dist: rdkit>=2024.9; extra == "rdkit"
Description-Content-Type: text/markdown

# ChargeFW for Python

ChargeFW calculates empirical partial atomic charges through Python bindings to its native C++
calculation engine. It provides bundled methods and parameter sets, deterministic applicability and
execution planning, source-ordered result mapping, molecular-file input, result JSON, MOL2 and mmCIF
output, and optional Gemmi and RDKit integration.

ChargeFW expects prepared molecular graphs with formal charges and any coordinates required by the
selected method. It does not parse SMILES, add hydrogens, choose protonation states, perceive arbitrary
bonds, or generate coordinates.

## Installation

ChargeFW requires Python 3.10 or newer:

```bash
pip install chargefw
```

Install an optional toolkit integration when converting existing toolkit objects:

```bash
pip install "chargefw[gemmi]"
pip install "chargefw[rdkit]"
```

The base package can read PDB and mmCIF text through its compiled Gemmi dependency without installing
the Gemmi Python package.

## Python usage

### From a molecular file

```python
import chargefw

molecules = chargefw.io.read("molecule.sdf", format="sdf")
result = chargefw.calculate(
    molecules,
    method="qeq",
    parameter_set="QEq_original",
    execution="full",
)
print(result.assignments[0].values)
```

For reproducible scientific work, select both the method and its parameter set when the method uses
one. Automatic selection is deterministic, but catalog priority is not a recommendation that a model
or parameterization is scientifically preferable for a particular molecule.

### From arrays

```python
import chargefw

molecule = chargefw.Molecule(
    atomic_numbers=[8, 1, 1],
    formal_charges=[0, 0, 0],
    bonds=[[0, 1, 1], [0, 2, 1]],
    coordinates=[
        [0.0, 0.0, 0.0],
        [0.96, 0.0, 0.0],
        [-0.24, 0.93, 0.0],
    ],
    name="water",
)

result = chargefw.calculate(
    molecule,
    method="qeq",
    parameter_set="QEq_original",
    execution="full",
)
print(result.assignments[0].values)
```

Write a complete result record with `chargefw.io.write()`:

```python
chargefw.io.write("charges.json", result, format="result-json")
```

## Documentation

- **[Python API](https://github.com/krab1k/chargefw/blob/main/docs/PYTHON.md)** - read molecules,
  calculate charges, and inspect methods and results.
- **[Python recipes](https://github.com/krab1k/chargefw/tree/main/docs/recipes)** - run complete SDF,
  Gemmi, RDKit, and parameter-set workflows.
- **[Molecular formats](https://github.com/krab1k/chargefw/blob/main/docs/FORMATS.md)** - check
  supported input, output, parsing, and mapping semantics.
- **[Project design](https://github.com/krab1k/chargefw/blob/main/docs/PROJECT.md)** - understand the
  architecture and scientific scope.
- **[Source repository](https://github.com/krab1k/chargefw)** - browse the source and report issues.

ChargeFW is distributed under the MIT license.
