Metadata-Version: 2.4
Name: openlca-ipc
Version: 0.4.0
Summary: A Python library for interacting with openLCA desktop application through the IPC protocol for life cycle assessment (LCA) workflows.
Author-email: Ernest Boakye Danquah <dernestbanksch@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/SDAI-institute/openlca-ipc
Project-URL: Documentation, https://github.com/SDAI-institute/openlca-ipc/tree/main/docs
Project-URL: Repository, https://github.com/SDAI-institute/openlca-ipc
Project-URL: Issues, https://github.com/SDAI-institute/openlca-ipc/issues
Keywords: openlca,lca,life-cycle-assessment,ipc,environmental-impact,iso-14040,iso-14044
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: olca-ipc>=2.6.0
Requires-Dist: olca-schema>=2.6.0
Requires-Dist: numpy>=1.24.0
Provides-Extra: full
Requires-Dist: matplotlib>=3.7.0; extra == "full"
Requires-Dist: pandas>=2.0.0; extra == "full"
Requires-Dist: scipy>=1.10.0; extra == "full"
Requires-Dist: openpyxl>=3.1.0; extra == "full"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: scipy>=1.10.0; extra == "dev"
Requires-Dist: openpyxl>=3.1.0; extra == "dev"
Provides-Extra: viz
Requires-Dist: matplotlib>=3.7.0; extra == "viz"
Requires-Dist: seaborn>=0.12.0; extra == "viz"
Provides-Extra: export
Requires-Dist: pandas>=2.0.0; extra == "export"
Requires-Dist: openpyxl>=3.1.0; extra == "export"
Dynamic: license-file

# openLCA IPC Python Library

A comprehensive Python library for interacting with openLCA desktop application through the IPC (Inter-Process Communication) protocol. Built for life cycle assessment (LCA) workflows based on ISO-14040/14044 standards.

[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![openLCA](https://img.shields.io/badge/openLCA-2.x-orange.svg)](https://www.openlca.org/)
[![DOI](https://zenodo.org/badge/1082686834.svg)](https://doi.org/10.5281/zenodo.17567634)

You can cite all versions by using the DOI 10.5281/zenodo.17567634. This DOI represents all versions, and will always resolve to the latest one.

## Features

- **Simple, Pythonic API** - High-level utilities that abstract complex IPC operations
- **Comprehensive LCA Workflow** - Search, create, calculate, and analyze in one package
- **Contribution Tree** - Recursive upstream contribution trees with depth/share pruning
- **Full LCI Inventory** - Elementary-flow inventory with input/output direction filter
- **Normalization & Weighting** - Normalized and weighted impacts in consistent dict format
- **Sankey Data** - Sankey graph data as plain dicts for visualization or MCP tools
- **Scenario Comparison** - `compare_systems()` returns per-category difference tables
- **Uncertainty Analysis** - Monte Carlo simulations with statistical summaries
- **Parameter Scenarios** - Sensitivity analysis over named parameters
- **Export Utilities** - CSV and Excel export for results
- **Agent Layer** - Compact JSON summaries, reproducibility metadata, and recoverable structured errors for AI agents and MCP servers
- **Read-Only Safe Mode** - `OLCAClient(read_only=True)` blocks all writes at the Python layer
- **Result Consistency Checks** - Runtime invariant warnings when contributions diverge from totals
- **ISO Compliant** - Follows ISO-14040/14044 LCA standards

## Installation

### Prerequisites

- Python 3.10 or higher
- openLCA desktop application (version 2.x)
- openLCA IPC server running (Tools → Developer Tools → IPC Server)

### Install from PyPI

```bash
pip install openlca-ipc
```

### Install from Source

```bash
# Clone the repository
git clone https://github.com/SDAI-institute/openlca-ipc.git
cd openlca-ipc

# Install in editable mode
pip install -e .

# Or install with optional dependencies
pip install -e ".[full]"
```

### Install Dependencies

```bash
# Core dependencies only
pip install -r requirements.txt

# Development dependencies
pip install -r requirements-dev.txt
```

## Quick Start

### 1. Start openLCA IPC Server

Before using the library, start the IPC server in openLCA:

1. Open openLCA desktop application
2. Go to **Tools → Developer Tools → IPC Server**
3. Click **Start** (default port: 8080)

### 2. Basic Usage

```python
from openlca_ipc import OLCAClient

# Connect to openLCA
with OLCAClient(port=8080) as client:
    # Test connection
    if client.test_connection():
        print("Connected to openLCA!")

    # Search for a material
    steel_flow = client.search.find_flow(['steel', 'production'])
    print(f"Found: {steel_flow.name}")

    # Find provider process
    provider = client.search.find_best_provider(steel_flow)
    print(f"Provider: {provider.name if provider else 'None'}")
```

## Usage Examples

### Example 1: Complete LCA Workflow

```python
from openlca_ipc import OLCAClient

with OLCAClient(port=8080) as client:
    # 1. Search for materials
    steel = client.search.find_flow(['steel'])
    steel_provider = client.search.find_best_provider(steel)

    # 2. Create a new process
    product = client.data.create_product_flow("Steel plate")
    exchanges = [
        client.data.create_exchange(product, 1.0, is_input=False, is_quantitative_reference=True),
        client.data.create_exchange(steel, 1.0, is_input=True, provider=steel_provider)
    ]
    process = client.data.create_process("Plate production", exchanges=exchanges)

    # 3. Create product system
    system = client.systems.create_product_system(process)

    # 4. Select impact method
    method = client.search.find_impact_method(['TRACI'])

    # 5. Calculate impacts
    result = client.calculate.simple_calculation(system, method)

    # 6. Get results
    impacts = client.results.get_total_impacts(result)
    for impact in impacts:
        print(f"{impact['name']}: {impact['amount']:.4e} {impact['unit']}")

    # 7. Clean up
    result.dispose()
```

### Example 2: Contribution Analysis

```python
from openlca_ipc import OLCAClient

client = OLCAClient(port=8080)

# Run calculation with contribution analysis
result = client.calculate.contribution_analysis(system, method)

# Get all impacts
impacts = client.results.get_total_impacts(result)

# Analyze top contributors for each impact
for impact in impacts:
    print(f"\n{impact['name']}:")

    # Get top 5 contributors
    contributors = client.contributions.get_top_contributors(
        result,
        impact['category'],
        n=5,
        min_share=0.01  # Minimum 1% contribution
    )

    for i, contrib in enumerate(contributors, 1):
        print(f"  {i}. {contrib.name}: {contrib.share*100:.1f}% ({contrib.amount:.4e})")

result.dispose()
```

### Example 3: Monte Carlo Uncertainty Analysis

```python
from openlca_ipc import OLCAClient
import matplotlib.pyplot as plt

client = OLCAClient(port=8080)

# Run Monte Carlo simulation
results = client.uncertainty.run_monte_carlo(
    system=my_system,
    impact_method=traci_method,
    iterations=1000,
    progress_callback=lambda i, total: print(f"Progress: {i}/{total}")
)

# Analyze global warming potential
gwp_key = next(k for k in results.keys() if 'warming' in k.lower())
gwp_result = results[gwp_key]

print(f"Mean: {gwp_result.mean:.4e}")
print(f"Std Dev: {gwp_result.std:.4e}")
print(f"CV: {gwp_result.cv:.2%}")
print(f"95% CI: [{gwp_result.percentile_5:.4e}, {gwp_result.percentile_95:.4e}]")

# Plot distribution
plt.figure(figsize=(10, 6))
plt.hist(gwp_result.values, bins=50, edgecolor='black', alpha=0.7)
plt.axvline(gwp_result.mean, color='red', linestyle='--', label='Mean')
plt.xlabel('Global Warming Potential')
plt.ylabel('Frequency')
plt.title('Monte Carlo Simulation Results')
plt.legend()
plt.savefig('gwp_distribution.png')
```

### Example 4: Scenario Analysis

```python
from openlca_ipc import OLCAClient
import pandas as pd

client = OLCAClient(port=8080)

# Analyze how transport distance affects impacts
scenarios = client.parameters.run_scenario_analysis(
    system=transport_system,
    impact_method=traci_method,
    parameter_name='transport_distance',
    values=[100, 200, 500, 1000, 2000, 5000]
)

# Create comparison DataFrame
data = []
for distance, impacts in scenarios.items():
    row = {'Distance (km)': distance}
    for impact in impacts:
        row[impact['name']] = impact['amount']
    data.append(row)

df = pd.DataFrame(data)
print(df)

# Export to CSV
client.export.export_comparison_to_csv(scenarios, 'scenario_results.csv')
```


## Module Overview

The library is organized into specialized modules:

- **`OLCAClient`** - Main client for connecting to openLCA IPC server (`read_only=True` for safe mode)
- **`search`** - Search and discovery utilities; `get_by_name()` for exact lookup
- **`data`** - Create and modify flows, exchanges, and processes
- **`systems`** - Build and configure product systems
- **`calculate`** - Run LCA calculations and `compare_systems()` scenario comparisons
- **`results`** - Impacts, inventory, normalization, weighting, Sankey, requirements
- **`contributions`** - Top contributors and recursive contribution trees
- **`uncertainty`** - Monte Carlo simulations and statistical analysis
- **`parameters`** - Parameter scenarios and sensitivity analysis
- **`export`** - Export results to CSV, Excel, and other formats
- **`agent`** - Compact JSON summaries, reproducibility context, structured errors, health check
- **`diagnostics`** - Runtime result consistency checks

## Best Practices

### 1. Always Dispose Results

```python
# Good - automatic cleanup with context manager
with OLCAClient(port=8080) as client:
    result = client.calculate.simple_calculation(system, method)
    impacts = client.results.get_total_impacts(result)
    result.dispose()  # Always dispose!

# Also good - explicit cleanup
client = OLCAClient(port=8080)
try:
    result = client.calculate.simple_calculation(system, method)
    # Process results
finally:
    result.dispose()
```

### 2. Handle Missing Data

```python
# Always check search results
pet_flow = client.search.find_flow(['polyethylene', 'terephthalate'])

if not pet_flow:
    # Try alternative keywords
    pet_flow = client.search.find_flow(['PET'])

if not pet_flow:
    print("Material not found in database")
    return

# Proceed safely
provider = client.search.find_best_provider(pet_flow)
```

### 3. Use Logging

```python
import logging

# Enable logging to see what's happening
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

# Library modules will log automatically
client = OLCAClient(port=8080)
# Output: "INFO - Connected to openLCA IPC server on port 8080"
```

## Documentation

- **[Quick Start](https://github.com/SDAI-institute/openlca-ipc/blob/main/documentation/quickstart.md)** - Step-by-step guide including v0.4 analysis functions
- **[Agent & MCP Guide](https://github.com/SDAI-institute/openlca-ipc/blob/main/documentation/agent-usage.md)** - Structured responses, reproducibility, safe mode
- **[API Reference](https://github.com/SDAI-institute/openlca-ipc/blob/main/documentation/api/README.md)** - All modules and methods
- **[Setup Guide](https://github.com/SDAI-institute/openlca-ipc/blob/main/documentation/installation.md)** - Detailed installation and configuration
- **[Examples](https://github.com/SDAI-institute/openlca-ipc/tree/main/examples)** - Working example scripts
- **[Complete Documentation](https://github.com/SDAI-institute/openlca-ipc/blob/main/documentation/index.md)** - Full documentation hub

## Requirements

### Core Dependencies

- `olca-ipc>=2.4.0` - openLCA IPC protocol implementation
- `olca-schema>=2.4.0` - openLCA data schema
- `numpy>=1.24.0` - Numerical operations

### Optional Dependencies

Install with `pip install openlca-ipc[full]`:

- `scipy>=1.10.0` - Statistical analysis for uncertainty
- `matplotlib>=3.7.0` - Visualization
- `pandas>=2.0.0` - Data export and analysis

## Development

### Setting Up Development Environment

```bash
# Clone repository
git clone https://github.com/SDAI-institute/openlca-ipc.git
cd openlca-ipc

# Create conda environment (if using conda)
conda create -n openlca_dev python=3.11
conda activate openlca_dev

# Install in editable mode with dev dependencies
pip install -e ".[full]"
pip install -r requirements-dev.txt
```


## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## Troubleshooting

### Connection Refused Error

**Problem**: Cannot connect to openLCA IPC server

**Solution**:
1. Ensure openLCA desktop application is running
2. Start IPC server: Tools → Developer Tools → IPC Server
3. Check port number (default: 8080)
4. Verify firewall settings

### Material Not Found

**Problem**: Search returns `None` for materials

**Solution**:
1. Check if the material exists in your openLCA database
2. Try different search keywords
3. Use partial matching: `client.search.find_flows(['steel'])` instead of exact names

### Zero Impact Values

**Problem**: All impact values are zero or very small

**Solution**:
1. Verify that input exchanges have providers linked
2. Check that the product system was created correctly
3. Ensure the impact method is appropriate for your flows
4. Verify that your database has characterization factors

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Citation

If you use this library in your research, please cite:

```bibtex
@software{openlca_ipc,
  author = {Danquah Boakye, Ernest},
  title = {openLCA IPC Python Library},
  year = {2025},
  url = {https://github.com/SDAI-institute/openlca-ipc}
}
```

## Acknowledgments

- Built on top of [olca-ipc](https://github.com/GreenDelta/olca-ipc.py) and [olca-schema](https://github.com/GreenDelta/olca-schema)
- Follows [ISO 14040](https://www.iso.org/standard/37456.html) and [ISO 14044](https://www.iso.org/standard/38498.html) standards
- Inspired by the openLCA community and LCA practitioners worldwide

## Support

- **Issues**: [GitHub Issues](https://github.com/SDAI-institute/openlca-ipc/issues)
- **Documentation**: [Read the Docs](https://github.com/SDAI-institute/openlca-ipc/blob/main/documentation/DOCUMENTATION_MAP.md)
- **Email**: dernestbanksch@gmail.com

---

**Made with ❤️ for the LCA Community**


