Metadata-Version: 2.4
Name: atct
Version: 1.0.0
Summary: ATcT: Active Thermochemical Tables — Python client for v1 API
Project-URL: Homepage, https://example.com/ATcT
Project-URL: Issues, https://example.com/ATcT/issues
Author: ATcT Team
License: BSD 3-Clause License
        
        Copyright (c) 2025, UChicago Argonne, LLC
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
License-File: LICENSE
Keywords: ATcT,chemistry,data,science,thermochemistry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.9
Requires-Dist: httpx>=0.25.0
Provides-Extra: all
Requires-Dist: numpy>=1.20; extra == 'all'
Requires-Dist: pandas>=2.0; extra == 'all'
Provides-Extra: numpy
Requires-Dist: numpy>=1.20; extra == 'numpy'
Provides-Extra: pandas
Requires-Dist: pandas>=2.0; extra == 'pandas'
Description-Content-Type: text/markdown

# atct - Pythonic ATcT v1 API Client

A comprehensive Python client for the ATcT v1 API with advanced reaction enthalpy calculation capabilities.

## Features

- **Complete v1 API coverage** - all endpoints implemented with proper error handling
- **Reaction calculations** - advanced uncertainty propagation with multiple methods
- **Minimal dependencies** - works with only Python standard library and httpx
- **Optional enhancements** - numpy for advanced calculations, pandas for DataFrames
- **Dual import support** - use `from atct.api import ...` or `from atct import ...`
- **Robust error handling** - comprehensive exception mapping and retry logic
- **Environment flexibility** - local/production URL switching

## Installation

```bash
# Basic installation (httpx only)
pip install atct

# With pandas support for DataFrames
pip install atct[pandas]

# With numpy support for advanced reaction calculations
pip install atct[numpy]

# With both pandas and numpy
pip install atct[all]
```

## Quickstart

```python
from atct.api import get_species, search_species, calculate_reaction_enthalpy

# Get species data
species = get_species("67-56-1*0")  # Methanol
print(f"{species.name}: {species.delta_h_298k} ± {species.delta_h_298k_uncertainty} kJ/mol")

# Search for species
results = search_species("methanol", limit=5)
for item in results.items:
    print(f"{item.name} ({item.atct_id})")

# Calculate reaction enthalpy (298.15K values, default)
species_data = {
    '67-56-1*0': -1.0,    # CH3OH (reactant)
    '7727-37-9*0': -1.5,  # O2 (reactant) 
    '124-38-9*0': 1.0,    # CO2 (product)
    '7732-18-5*0': 2.0    # H2O (product)
}
result_298k = calculate_reaction_enthalpy(species_data, 'covariance')
print(f"298.15K reaction enthalpy: {result_298k}")

# Calculate reaction enthalpy with 0K values (conventional method only, fails if 0K not available for any species)
try:
    result_0k = calculate_reaction_enthalpy(species_data, 'conventional', use_0k=True)
    print(f"0K reaction enthalpy: {result_0k}")
except ValueError as e:
    print(f"Cannot use 0K values: {e}")
```

## API Functions

### Species Data
- `get_species(atctid, expand_xyz=False)` - Get species by ATcT ID
- `search_species(q, limit=50, offset=0)` - Search species by name or formula
- `get_species_by_smiles(smiles)` - Get species by SMILES string
- `get_species_by_casrn(casrn)` - Get species by CAS Registry Number
- `get_species_by_inchi(inchi)` - Get species by InChI
- `get_species_by_formula(formula, phase=None, descriptor=None)` - Get species by formula
- `get_species_by_name(name)` - Get species by name

### Covariance Data
- `get_species_covariance_by_atctid(a_atctid, b_atctid)` - Get 2x2 covariance matrix
- `get_species_covariance_by_ids(a_id, b_id)` - Get covariance by numeric IDs

### Reaction Calculations
- `calculate_reaction_enthalpy(species_data, method, use_0k=False)` - Calculate reaction enthalpy
  - `use_0k=True`: Use 0K enthalpy values with conventional method only (fails if not available for any species)
  - `use_0k=False`: Use 298.15K enthalpy values (default)
- `create_reaction_calculator(species_data, use_0k=False)` - Create reaction calculator

**Note:** The `covariance` method requires numpy (`pip install atct[numpy]`) and should only be used with 298.15K values. 
The `conventional` method works without external dependencies and is used for 0K calculations.
A warning will be issued if covariance method is used with 0K values, as the covariance matrix is only valid at 298.15K (the temperature the Thermochemical Network was solved at).

### Utility
- `healthcheck()` - Check API health status
- `as_dataframe(items)` - Convert results to pandas DataFrame

## Data Models

### Species
```python
@dataclass
class Species:
    atct_tn_version: Optional[str]
    atct_id: str
    name: Optional[str]
    formula: Optional[str]
    delta_h_0k: Optional[str]
    delta_h_298k: Optional[str]
    delta_h_298k_uncertainty: Optional[str]
    unit: Optional[str]
    mass: Optional[str]
    mass_uncertainty: Optional[str]
    smiles: Optional[str]
    casrn: Optional[str]
    charge: Optional[int]
    xyz: Optional[Union[str, List[str]]]
```

### Covariance2x2
```python
@dataclass
class Covariance2x2:
    labels: List[str]
    units: str
    matrix: List[List[float]]  # 2x2 matrix
```

### Reaction Models
```python
@dataclass
class ReactionSpecies:
    species: Species
    stoichiometry: float

@dataclass
class ReactionResult:
    delta_h: float
    uncertainty: float
    method: str
    units: str = "kJ/mol"
```

## Error Handling

The package provides specific exceptions for different error conditions:

```python
from atct import ATCTError, NotFound, BadRequest, Unauthorized, ServerError, NetworkError

try:
    species = get_species("invalid-id")
except NotFound:
    print("Species not found")
except NetworkError:
    print("Network connection failed")
except ATCTError as e:
    print(f"API error: {e}")
```

## Configuration

Set environment variables to configure the client:

- `ATCT_API_BASE_URL` (default: `https://atct.anl.gov/api/v1`) - API endpoint
- `ATCT_API_KEY` (optional, for authenticated requests)
- `ATCT_TIMEOUT_S` (default: `10` seconds)
- `ATCT_RETRIES` (default: `3` retry attempts)
- `ATCT_USER_AGENT` (default: `atct/1.0.0`)

The client uses the v1 API exclusively.

## Development

```bash
# Install in editable mode
pip install -e .

# Run tests
pytest -q

# Run examples
python examples/example_usage.py
python examples/example_reaction_calculations.py
```

## Examples

See the `examples/` directory for comprehensive usage examples:
- `example_usage.py` - Basic API functionality
- `example_reaction_calculations.py` - Advanced reaction calculations

## v1 API Endpoints

This package targets the ATcT v1 API exclusively:

- `GET /api/v1/health` - Health check
- `GET /api/v1/species/get/by-atctid/` - Get species by ATcT ID
- `GET /api/v1/species/search/` - Search species
- `GET /api/v1/species/get/by-smiles/` - Get species by SMILES
- `GET /api/v1/species/get/by-casrn/` - Get species by CASRN
- `GET /api/v1/species/get/by-inchi/` - Get species by InChI
- `GET /api/v1/species/get/by-formula/` - Get species by formula
- `GET /api/v1/species/get/by-name/` - Get species by name
- `GET /api/v1/covariance/species/` - Get covariance matrices
