approximate 0.1.0__tar.gz

approximate-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RAMP-Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

approximate-0.1.0/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: approximate
+Version: 0.1.0
+Summary: Composition-only mixed oxidation state estimation, charge balancing and capacity prediction for inorganic materials.
+Author-email: Fay Timen <fay.a.timen@gmail.com>, "Thomas E. Ashton" <t.ashton@ucl.ac.uk>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/RAMP-Labs/ApprOxiMate
+Project-URL: Source, https://github.com/RAMP-Labs/ApprOxiMate
+Project-URL: Issues, https://github.com/RAMP-Labs/ApprOxiMate/issues
+Keywords: oxidation state,charge balance,materials informatics,featurisation,battery,cathode
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Provides-Extra: features
+Requires-Dist: mendeleev>=0.17; extra == "features"
+Requires-Dist: pymatgen>=2024.0.0; extra == "features"
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.7; extra == "plot"
+Provides-Extra: all
+Requires-Dist: approximate[features,plot]; extra == "all"
+Provides-Extra: dev
+Requires-Dist: approximate[all]; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: jupyter; extra == "dev"
+Requires-Dist: tqdm; extra == "dev"
+Dynamic: license-file
+
+# ApprOxiMate
+
+ApprOxiMate is a Python package for charge balancing inorganic chemical
+formulae and generating oxidation-state-aware descriptors for materials
+informatics workflows.
+
+The project combines a charge-balancing routine with feature engineering
+modules for valence structure, elemental properties, ionic radii,
+electronegativity, magnetic moments, and related composition statistics.
+It is designed for use in notebooks and machine-learning pipelines where
+oxidation states provide useful chemical context beyond formula-only
+descriptors.
+
+## Features
+
+- Charge balance inorganic formulae using fixed and variable oxidation-state
+  data.
+- Return balanced results as strings, dictionaries, pandas DataFrames, or
+  structured Python objects.
+- Generate descriptors for all elements in a composition and for variable
+  oxidation-state elements separately.
+- Build feature matrices from lists of formulae for downstream modelling.
+- Includes example notebooks for featurisation, exploratory analysis, model
+  training, and result assessment.
+
+## Standard Reduction Potential Data
+NIST dataset was used to collected SRP values used within the variable_ox_states_srps.csv 
+
+S. G. Bratsch, Standard Electrode Potentials and Temperature Coefficients in Water at 298.15 K, Journal of Physical and Chemical Reference Data, 1989, 18, 1–21.
+
+## Citation
+Please cite this package.
+
+## Installation
+
+```bash
+pip install approximate
+```
+
+For development, clone the repository and install it in editable mode:
+
+```bash
+git clone https://github.com/RAMP-Labs/ApprOxiMate.git
+cd ApprOxiMate
+python -m pip install -e .
+```
+
+For notebook and development dependencies:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+ApprOxiMate requires Python 3.10 or newer.
+
+## Quick Start
+
+```python
+from approximate import charge_balance
+
+r = charge_balance("Fe3O4")
+print(r)                # O:-2:4.0;Fe:2:1.0;Fe:3:2.0;FinalChargeBalance:0.0
+r.oxidation_states      # one entry per (element, oxidation state)
+r.final_charge          # 0.0
+r.is_balanced           # True
+r.to_dataframe()        # oxidation states as a table
+r.to_dict()             # everything as a dictionary
+```
+
+Shortcuts when you only need one thing:
+
+```python
+from approximate import oxidation_states, final_charge, parse_formula
+
+oxidation_states("LiFePO4")                     # list of states
+oxidation_states("LiFePO4", as_dataframe=True)  # as a DataFrame
+final_charge("NaMn0.5Ni0.5O2")                  # 0.0
+parse_formula("LiFePO4")                        # {'Li': 1.0, 'Fe': 1.0, 'P': 1.0, 'O': 4.0}
+```
+
+Every function accepts `verbose=True` (step-by-step log) and `precision=`.
+
+## Feature Engineering
+
+Use `MaterialFeatureExtractor` to generate oxidation-state-aware features for
+one formula or many formulae:
+
+```python
+import pandas as pd
+from approximate.feature_engineering import MaterialFeatureExtractor
+
+# The periodic table is loaded from mendeleev automatically.
+# Pass your own as the first argument to reuse or customise it.
+extractor = MaterialFeatureExtractor(mode="both", ionic_radius_unit="pm")
+
+features = extractor.get_features("LiFePO4")
+feature_table = pd.DataFrame(
+    extractor.featurize_many(["LiFePO4", "NaCoO2"])
+)
+```
+
+`mode` controls which feature groups are returned:
+
+- `"all"`: descriptors calculated over all elements in the formula.
+- `"var"`: descriptors calculated only over variable oxidation-state elements.
+- `"both"`: include both groups.
+
+The available feature modules include:
+
+- `ValenceFeatureModule`
+- `ElementPropertyModule`
+- `IonicRadiusModule`
+- `MagneticMomentModule`
+- `ElectronegativityModule`
+- `TransitionMetalPotentialModule`
+
+The transition-metal potential module is optional and can be enabled with:
+
+```python
+extractor = MaterialFeatureExtractor(
+    enable_tm_potential=True,
+    tm_cation="Na",
+    tm_anion="O",
+)
+```
+
+## Notebooks
+
+The repository includes notebooks that demonstrate the main workflow:
+
+- `tutorial_notebook.ipynb`: introductory charge-balancing examples.
+- `notebooks/exp1_featurisation.ipynb`: dataset featurisation.
+- `notebooks/exp2_EDA_of_dataset.ipynb`: exploratory data analysis.
+- `notebooks/exp3a_approx_runML.ipynb`: modelling with ApprOxiMate features.
+- `notebooks/exp3b_magpie_runML.ipynb`: comparison modelling with Magpie-style features.
+- `notebooks/exp3c_oliynyk_runML.ipynb`: comparison modelling with Oliynyk-style features.
+- `notebooks/exp4_assessing_models.ipynb`: model assessment and visualisation.
+
+Notebooks with `exp0_` in the front show multiple ways to use ApprOxiMate outside of feature engineering and machine learning. Such as:
+
+- `alkali_removal_notebook.ipynb`: Charge balance plots and theoretical oxidation state tracking.
+- `parity_plot_theo_cap.ipynb`: Adjust theoretical capacity calculations using ApprOxiMates charge balance assessment. 
+- `srp_analysis.ipynb`: Since the user is able to change the SRP data to what fits their needs, this notebook helps visualise this.
+
+## Project Layout
+
+```text
+approximate/
+  core.py                     # Charge-balancing engine and public functions
+  Data/                       # Oxidation-state and SRP lookup data
+  feature_engineering/        # Descriptor modules and feature extractor
+notebooks/                    # Experiments, datasets, outputs, and analysis
+site/                         # Web calculator (GitHub Pages, runs in-browser via Pyodide)
+tutorial_notebook.ipynb       # Introductory usage notebook
+```
+
+### Data Cleanup Note
+An earlier version of Parsed_Data.csv contained 2,302 raw entries. The current Parsed_Data.csv now has 2,299 raw entries as 3 formula were lost when transferred over to ICSD_CrystStrucData.csv. This 2,299 dataset was then preprocessed and cleaned resulting in a dataset of 2,283 entires as seen in `notebooks/exp1_featurisation.ipynb` these 16 formulas were removed due to numerical precision limits encountered when parsing and balancing large formula units and therfore were unable to be charge balanced successfully. 
+
+## License
+
+This project is licensed under the MIT License. See `LICENSE` for details.

approximate-0.1.0/README.md

@@ -0,0 +1,162 @@
+# ApprOxiMate
+
+ApprOxiMate is a Python package for charge balancing inorganic chemical
+formulae and generating oxidation-state-aware descriptors for materials
+informatics workflows.
+
+The project combines a charge-balancing routine with feature engineering
+modules for valence structure, elemental properties, ionic radii,
+electronegativity, magnetic moments, and related composition statistics.
+It is designed for use in notebooks and machine-learning pipelines where
+oxidation states provide useful chemical context beyond formula-only
+descriptors.
+
+## Features
+
+- Charge balance inorganic formulae using fixed and variable oxidation-state
+  data.
+- Return balanced results as strings, dictionaries, pandas DataFrames, or
+  structured Python objects.
+- Generate descriptors for all elements in a composition and for variable
+  oxidation-state elements separately.
+- Build feature matrices from lists of formulae for downstream modelling.
+- Includes example notebooks for featurisation, exploratory analysis, model
+  training, and result assessment.
+
+## Standard Reduction Potential Data
+NIST dataset was used to collected SRP values used within the variable_ox_states_srps.csv 
+
+S. G. Bratsch, Standard Electrode Potentials and Temperature Coefficients in Water at 298.15 K, Journal of Physical and Chemical Reference Data, 1989, 18, 1–21.
+
+## Citation
+Please cite this package.
+
+## Installation
+
+```bash
+pip install approximate
+```
+
+For development, clone the repository and install it in editable mode:
+
+```bash
+git clone https://github.com/RAMP-Labs/ApprOxiMate.git
+cd ApprOxiMate
+python -m pip install -e .
+```
+
+For notebook and development dependencies:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+ApprOxiMate requires Python 3.10 or newer.
+
+## Quick Start
+
+```python
+from approximate import charge_balance
+
+r = charge_balance("Fe3O4")
+print(r)                # O:-2:4.0;Fe:2:1.0;Fe:3:2.0;FinalChargeBalance:0.0
+r.oxidation_states      # one entry per (element, oxidation state)
+r.final_charge          # 0.0
+r.is_balanced           # True
+r.to_dataframe()        # oxidation states as a table
+r.to_dict()             # everything as a dictionary
+```
+
+Shortcuts when you only need one thing:
+
+```python
+from approximate import oxidation_states, final_charge, parse_formula
+
+oxidation_states("LiFePO4")                     # list of states
+oxidation_states("LiFePO4", as_dataframe=True)  # as a DataFrame
+final_charge("NaMn0.5Ni0.5O2")                  # 0.0
+parse_formula("LiFePO4")                        # {'Li': 1.0, 'Fe': 1.0, 'P': 1.0, 'O': 4.0}
+```
+
+Every function accepts `verbose=True` (step-by-step log) and `precision=`.
+
+## Feature Engineering
+
+Use `MaterialFeatureExtractor` to generate oxidation-state-aware features for
+one formula or many formulae:
+
+```python
+import pandas as pd
+from approximate.feature_engineering import MaterialFeatureExtractor
+
+# The periodic table is loaded from mendeleev automatically.
+# Pass your own as the first argument to reuse or customise it.
+extractor = MaterialFeatureExtractor(mode="both", ionic_radius_unit="pm")
+
+features = extractor.get_features("LiFePO4")
+feature_table = pd.DataFrame(
+    extractor.featurize_many(["LiFePO4", "NaCoO2"])
+)
+```
+
+`mode` controls which feature groups are returned:
+
+- `"all"`: descriptors calculated over all elements in the formula.
+- `"var"`: descriptors calculated only over variable oxidation-state elements.
+- `"both"`: include both groups.
+
+The available feature modules include:
+
+- `ValenceFeatureModule`
+- `ElementPropertyModule`
+- `IonicRadiusModule`
+- `MagneticMomentModule`
+- `ElectronegativityModule`
+- `TransitionMetalPotentialModule`
+
+The transition-metal potential module is optional and can be enabled with:
+
+```python
+extractor = MaterialFeatureExtractor(
+    enable_tm_potential=True,
+    tm_cation="Na",
+    tm_anion="O",
+)
+```
+
+## Notebooks
+
+The repository includes notebooks that demonstrate the main workflow:
+
+- `tutorial_notebook.ipynb`: introductory charge-balancing examples.
+- `notebooks/exp1_featurisation.ipynb`: dataset featurisation.
+- `notebooks/exp2_EDA_of_dataset.ipynb`: exploratory data analysis.
+- `notebooks/exp3a_approx_runML.ipynb`: modelling with ApprOxiMate features.
+- `notebooks/exp3b_magpie_runML.ipynb`: comparison modelling with Magpie-style features.
+- `notebooks/exp3c_oliynyk_runML.ipynb`: comparison modelling with Oliynyk-style features.
+- `notebooks/exp4_assessing_models.ipynb`: model assessment and visualisation.
+
+Notebooks with `exp0_` in the front show multiple ways to use ApprOxiMate outside of feature engineering and machine learning. Such as:
+
+- `alkali_removal_notebook.ipynb`: Charge balance plots and theoretical oxidation state tracking.
+- `parity_plot_theo_cap.ipynb`: Adjust theoretical capacity calculations using ApprOxiMates charge balance assessment. 
+- `srp_analysis.ipynb`: Since the user is able to change the SRP data to what fits their needs, this notebook helps visualise this.
+
+## Project Layout
+
+```text
+approximate/
+  core.py                     # Charge-balancing engine and public functions
+  Data/                       # Oxidation-state and SRP lookup data
+  feature_engineering/        # Descriptor modules and feature extractor
+notebooks/                    # Experiments, datasets, outputs, and analysis
+site/                         # Web calculator (GitHub Pages, runs in-browser via Pyodide)
+tutorial_notebook.ipynb       # Introductory usage notebook
+```
+
+### Data Cleanup Note
+An earlier version of Parsed_Data.csv contained 2,302 raw entries. The current Parsed_Data.csv now has 2,299 raw entries as 3 formula were lost when transferred over to ICSD_CrystStrucData.csv. This 2,299 dataset was then preprocessed and cleaned resulting in a dataset of 2,283 entires as seen in `notebooks/exp1_featurisation.ipynb` these 16 formulas were removed due to numerical precision limits encountered when parsing and balancing large formula units and therfore were unable to be charge balanced successfully. 
+
+## License
+
+This project is licensed under the MIT License. See `LICENSE` for details.

approximate-0.1.0/approximate/Data/fixed_ox_states.csv

@@ -0,0 +1,42 @@
+Element,Ox State
+H,1
+Li,1
+Na,1
+K,1
+Rb,1
+Cs,1
+Fr,1
+Be,2
+Mg,2
+Ca,2
+Sr,2
+Ba,2
+Ra,2
+Y,3
+La,3
+Gd,3
+Lu,3
+Ac,3
+Th,4
+Lr,3
+Zr,4
+Hf,4
+Zn,2
+Cd,2
+Hg,2
+B,3
+Al,3
+Ga,3
+O,-2
+Po,4
+F,-1
+Cl,-1
+Br,-1
+I,-1
+At,-1
+T,2
+D,3
+Er,3
+In,3
+Ho,3
+P,5

approximate-0.1.0/approximate/Data/variable_ox_states_srps.csv

@@ -0,0 +1,171 @@
+Element,Ox,Red,SRP (V)
+Sc,3,2,-2.3
+Sc,3,0,-2.09
+Sc,2,0,-2
+Ti,2,0,-1.63
+Ti,3,0,-1.37
+Ti,3,2,-0.37
+Ti,4,3,0.10
+Ce,3,0,-2.336
+Ce,4,3,1.71
+Pr,3,0,-2.353
+Nd,3,2,-2.7
+Nd,3,0,-2.323
+Nd,2,0,-2.1
+Pm,3,2,-2.6
+Pm,3,0,-2.3
+Pm,2,0,-2.2
+Eu,2,0,-2.812
+Eu,3,0,-1.991
+Eu,3,2,-0.35
+Tb,3,0,-2.28
+Dy,3,2,-2.6
+Dy,3,0,-2.295
+Dy,2,0,-2.2
+Tm,2,0,-2.4
+Tm,3,0,-2.319
+Tm,3,2,-2.2
+Yb,2,0,-2.76
+Yb,3,0,-2.19
+Yb,3,2,-1.05
+Pa,4,3,-1.9
+Pa,4,0,-1.49
+Pa,3,0,-1.34
+U,3,0,-1.642
+U,4,3,-0.577
+Np,3,0,-1.768
+Np,4,3,0.157
+Pu,3,2,-2.8
+Pu,3,0,-1.978
+Pu,2,0,-1.6
+Pu,4,3,1.006
+Am,3,2,-2.3
+Am,3,0,-2.048
+Am,2,0,-1.9
+Cm,3,0,-2.04
+Bk,3,2,-2.8
+Bk,3,0,-1.98
+Bk,2,0,-1.6
+Bk,4,3,1.67
+Cf,2,0,-2.12
+Cf,3,0,-1.94
+Cf,3,2,-1.6
+Es,2,0,-2.23
+Es,3,0,-1.91
+Es,3,2,-1.3
+Fm,2,0,-2.3
+Fm,3,0,-1.89
+Fm,3,2,-1.1
+Md,2,0,-2.4
+Md,3,0,-1.65
+Md,3,2,-0.1
+No,2,0,-2.5
+No,3,0,-1.2
+No,3,2,1.4
+V,2,0,-1.13
+V,3,2,-0.26
+V,4,3,0.337
+V,5,4,1.001
+Nb,3,0,-0.733
+Nb,5,0,-0.69
+Nb,5,3,-0.646
+Ta,5,0,-0.752
+Ta,3,0,-0.6
+Cr,2,0,-0.89
+Cr,3,0,-0.74
+Cr,3,2,-0.42
+Cr,6,3,1.36
+Mo,4,0,-0.152
+Mo,6,0,0.082
+Mo,6,4,0.2
+W,4,0,-1.54
+W,6,0,-0.091
+W,6,4,0.01
+Mn,2,0,-1.182
+Mn,4,3,0.98
+Mn,3,2,1.56
+Mn,7,4,2.09
+Tc,4,0,0.272
+Tc,7,0,0.427
+Tc,7,4,0.738
+Re,4,0,0.276
+Re,7,0,0.376
+Re,7,4,0.51
+Fe,2,0,-0.44
+Fe,3,2,0.771
+Ru,4,3,0.58
+Ru,3,0,0.6
+Ru,8,4,1.4
+Os,4,0,0.65
+Os,8,0,0.838
+Os,8,4,0.964
+Co,2,0,-0.282
+Co,3,0,0.003
+Co,4,3,1.42
+Co,3,2,1.92
+Ir,4,3,0.4
+Ir,4,0,0.73
+Ir,3,0,0.84
+Ni,2,0,-0.236
+Ni,4,0,0.055
+Ni,3,2,1.753
+Ni,4,3,2.05
+Pd,2,0,0.915
+Pd,4,2,1.27
+Pt,4,0,0.92
+Pt,4,2,1.01
+Pt,2,0,1.18
+Cu,2,1,0.161
+Cu,2,0,0.339
+Cu,1,0,0.518
+Ag,1,0,0.7993
+Ag,2,1,1.98
+Au,3,1,1.41
+Au,3,0,1.52
+Au,1,0,1.69
+Sm,2,0,-2.68
+Sm,3,0,-2.304
+Sm,3,2,-1.55
+Tl,1,0,-0.336
+Tl,3,0,0.741
+Tl,3,1,1.28
+C,4,2,-0.07
+C,4,0,0.2073
+C,2,0,0.5184
+Si,4,0,-0.931
+Si,0,-4,-0.147
+Ge,4,2,-2.07
+Ge,4,0,-0.104
+Ge,2,0,0.11
+Sn,2,0,-0.141
+Sn,4,0,-0.117
+Sn,4,2,-0.094
+Pb,2,0,-0.126
+Pb,4,0,1.23
+Pb,4,2,1.458
+Bi,3,0,0.308
+Bi,5,3,2
+S,0,-2,0.144
+S,6,4,0.158
+S,6,0,0.333
+S,4,0,0.458
+Te,0,-2,-0.46
+Te,4,0,0.529
+Te,6,4,0.84
+P,3,0,-0.402
+P,5,0,-0.377
+P,5,3,-0.3
+P,0,-3,-0.088
+Sb,3,0,0.231
+Sb,5,3,0.54
+As,3,0,0.234
+As,5,3,0.566
+N,0,-3,-3.334
+N,3,-3,-1.887
+N,3,0,1.447
+Rh,3,0,0.76
+Rh,4,0,0.83
+Rh,4,3,1.3
+Se,0,-2,-0.114
+Se,4,0,0.739
+Se,6,4,1.094

approximate-0.1.0/approximate/__init__.py

@@ -0,0 +1,31 @@
+"""ApprOxiMate: composition-only mixed oxidation state estimation.
+
+    from approximate import charge_balance
+    r = charge_balance("Fe3O4")
+"""
+from .capacity import CapacityResult, capacity, molar_mass
+from .sweep import SweepResult, alkali_sweep
+from .core import (
+    BalanceResult,
+    ElementState,
+    charge_balance,
+    final_charge,
+    oxidation_states,
+    parse_formula,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "charge_balance",
+    "oxidation_states",
+    "final_charge",
+    "parse_formula",
+    "capacity",
+    "molar_mass",
+    "CapacityResult",
+    "alkali_sweep",
+    "SweepResult",
+    "BalanceResult",
+    "ElementState",
+]