solubilityCCS 0.8.4

A Python package for analyzing solubility and acid formation behavior in Carbon Capture and Storage (CCS) systems

SolubilityCCS

A Python package for analyzing solubility and acid formation behavior in Carbon Capture and Storage (CCS) systems using advanced thermodynamic models.

Overview

SolubilityCCS provides tools to analyze acid formation risks in CO2 transport and storage systems. The package uses the SRK-CPA (Soave-Redlich-Kwong Cubic Plus Association) equation of state to calculate fugacity coefficients and activity models to determine component activities in multiphase systems.

Thermodynamic Models

• Fugacity calculations: SRK-CPA equation of state for prediction of component fugacities
• Activity calculations: Activity coefficient models for liquid phase behavior
• Phase equilibrium: Robust flash calculations for multiphase systems

Supported Systems

The model currently supports the following chemical systems:

• CO₂-water (binary system)
• CO₂-water-H₂SO₄ (ternary system with sulfuric acid)
• CO₂-water-HNO₃ (ternary system with nitric acid)

Coming Soon: CO₂-water-H₂SO₄-HNO₃ (quaternary system)

Applications

• Initial solubility estimates for acids in CO₂ streams
• Acid formation risk assessment in CCS transport pipelines
• Phase behavior analysis under various pressure and temperature conditions
• Liquid phase formation prediction and composition analysis

Installation

Requirements

• Python 3.9 or higher
• NeqSim (Java-based thermodynamic library)
• Scientific Python stack (NumPy, SciPy, Pandas, Matplotlib)

From PyPI (Recommended)

pip install solubilityCCS

From Source

git clone <repository-url>
cd SolubilityCCS
pip install -e .

Quick Start

Basic Acid Formation Analysis

from solubilityccs import Fluid
from solubilityccs.neqsim_functions import get_co2_parameters

# System parameters
acid = "H2SO4"  # Supported: "H2SO4", "HNO3"
acid_concentration = 10.0  # ppm
water_concentration = 10.0  # ppm
temperature = 2.0  # °C
pressure = 60.0  # bara
flow_rate = 100  # Mt/year

# Create fluid system
fluid = Fluid()
fluid.add_component("CO2", 1.0 - acid_concentration/1e6 - water_concentration/1e6)
fluid.add_component(acid, acid_concentration/1e6)
fluid.add_component("H2O", water_concentration/1e6)

# Set operating conditions
fluid.set_temperature(temperature + 273.15)  # Convert to Kelvin
fluid.set_pressure(pressure)
fluid.set_flow_rate(flow_rate * 1e6 * 1000 / (365 * 24), "kg/hr")

# Perform thermodynamic calculations
fluid.calc_vapour_pressure()
fluid.flash_activity()

# Analyze results
print(f"Gas phase fraction: {fluid.betta:.4f}")
print(f"Water in CO2: {1e6 * fluid.phases[0].get_component_fraction('H2O'):.2f} ppm")
print(f"{acid} in CO2: {1e6 * fluid.phases[0].get_component_fraction(acid):.2f} ppm")

# Check for liquid phase formation (acid formation risk)
if fluid.betta < 1.0:
    print("\n⚠️  ACID FORMATION RISK DETECTED!")
    print(f"Liquid phase type: {fluid.phases[1].name}")
    print(f"Liquid acid concentration: {fluid.phases[1].get_acid_wt_prc(acid):.2f} wt%")
    print(f"Liquid phase flow rate: {fluid.phases[1].get_flow_rate('kg/hr') * 24 * 365 / 1000:.2f} t/y")
else:
    print("\n✅ Single gas phase - No acid formation risk")

# Get pure CO2 properties
co2_props = get_co2_parameters(pressure, temperature)
print(f"\nPure CO2 properties at {temperature}°C, {pressure} bara:")
print(f"Density: {co2_props['density']:.2f} kg/m³")
print(f"Speed of sound: {co2_props['speed_of_sound']:.2f} m/s")
print(f"Enthalpy: {co2_props['enthalpy']:.2f} kJ/kg")
print(f"Entropy: {co2_props['entropy']:.2f} J/K")

Advanced Usage

from solubilityccs import Fluid
from solubilityccs.neqsim_functions import (
    get_acid_fugacity_coeff,
    get_water_fugacity_coefficient
)

# Calculate fugacity coefficients for different acids
h2so4_fug_coeff = get_acid_fugacity_coeff("H2SO4", 60.0, 2.0)
hno3_fug_coeff = get_acid_fugacity_coeff("HNO3", 60.0, 2.0)
water_fug_coeff = get_water_fugacity_coefficient(60.0, 2.0)

print(f"H2SO4 fugacity coefficient: {h2so4_fug_coeff}")
print(f"HNO3 fugacity coefficient: {hno3_fug_coeff}")
print(f"Water fugacity coefficient: {water_fug_coeff}")

Features

Core Functionality

• Thermodynamic property calculations using SRK-CPA equation of state
• Multiphase flash calculations with activity coefficient models
• Component fugacity and activity calculations
• Phase behavior analysis for CO2-acid-water systems
• Acid formation risk assessment for CCS applications

Supported Components

• CO₂ (Carbon dioxide)
• H₂O (Water)
• H₂SO₄ (Sulfuric acid)
• HNO₃ (Nitric acid)

Calculation Capabilities

• Vapor-liquid equilibrium calculations
• Component solubility predictions
• Liquid phase formation analysis
• Acid concentration calculations
• Pure component property estimation

Database Integration

• Built-in component database (COMP.csv)
• Thermodynamic property database (Properties.csv)
• Water activity data for H₂SO₄ systems

Examples

See the examples/ directory for more comprehensive examples:

• basic_usage.py: Simple acid formation analysis
• example.ipynb: Jupyter notebook with detailed workflow
• acid_formation_analysis.py: Advanced analysis scripts

Development Setup

Prerequisites

• Python 3.9 or higher
• Git
• Java Runtime Environment (for NeqSim)

Quick Start

1. Clone the repository:

   git clone <repository-url>
   cd SolubilityCCS
   

2. Install dependencies:

   make install-dev
   

3. Set up pre-commit hooks (REQUIRED):

   make setup-pre-commit
   

4. Run tests:

   make test
   

Pre-commit Hooks

This project uses pre-commit hooks to ensure code quality. All commits must pass pre-commit checks.

Pre-commit hooks include:

• Code formatting (black, isort)
• Linting (flake8)
• Type checking (mypy)
• Security scanning (bandit)
• Documentation style (pydocstyle)
• General code quality checks

To run pre-commit manually:

pre-commit run --all-files

Development Commands

# Install dependencies
make install-dev

# Set up pre-commit hooks
make setup-pre-commit

# Format code
make format

# Run linting
make lint

# Run type checking
make type-check

# Run security checks
make security-check

# Run tests
make test
make test-coverage
make test-unit
make test-integration

# Clean up artifacts
make clean

Testing

The package includes comprehensive tests covering:

• Unit tests for individual components
• Integration tests for complete workflows
• Validation tests against known data
• Path resolution tests for robust file handling

Run the test suite:

# Run all tests
make test

# Run with coverage
make test-coverage

# Run specific test categories
pytest test_fluid.py -v
pytest test_integration_validation.py -v

# Quick tests without coverage (faster)
python run_tests.py quick

Known Issue: Segmentation Fault in CI

You may occasionally see a segmentation fault (exit code 139) in CI after all tests pass successfully. This is a known issue that occurs during Python interpreter shutdown when using coverage reporting with certain C extensions (like NeqSim). The tests themselves pass correctly, and the segfault happens during cleanup.

Workaround: The CI workflows are configured to treat this as a success if the coverage report was generated successfully.

API Reference

Main Classes

• Fluid: Main class for fluid system creation and analysis
• Phase: Represents individual phases in the system
• AcidFormationAnalysis: Specialized analysis for acid formation risks

Key Functions

• get_co2_parameters(pressure, temperature): Calculate pure CO2 properties
• get_acid_fugacity_coeff(acid, pressure, temperature): Calculate acid fugacity coefficients
• get_water_fugacity_coefficient(pressure, temperature): Calculate water fugacity coefficients

Limitations and Considerations

1. Model applicability: Limited to CO2-water-acid systems
2. Pressure/temperature ranges: Validated for CCS-relevant conditions
3. Initial estimates: Results should be verified with experimental data when available
4. Mixing rules: Binary interaction parameters are system-specific

Contributing

Please see CONTRIBUTING.md for detailed contribution guidelines.

Important: Pre-commit hooks are required for all contributions. Make sure to run make setup-pre-commit after cloning the repository.

Release Process

This project uses automated releases via GitHub Actions. When you merge a pull request:

• Patch release (1.0.0 → 1.0.1): Default for bug fixes
• Minor release (1.0.0 → 1.1.0): Include "feat" or "feature" in PR title
• Major release (1.0.0 → 2.0.0): Include "breaking" or "major" in PR title

See RELEASE_PROCESS.md for detailed information.

Citation

If you use SolubilityCCS in your research, please cite:

@software{solubilityccs,
  title = {SolubilityCCS: A Python package for analyzing solubility and acid formation in CCS systems},
  author = {SolubilityCCS Contributors},
  url = {https://github.com/your-username/SolubilityCCS},
  version = {1.0.0},
  year = {2025}
}

License

See LICENSE for license information.

Support

For questions, issues, or contributions:

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [Contact information]

---

Note: This package provides initial estimates for acid solubilities in CO2 streams. For critical applications, results should be validated against experimental data or more detailed models.