Metadata-Version: 2.4
Name: processlab
Version: 0.1.0
Summary: A dynamic systems simulation library with computational graph capabilities
Author-email: Euan Russano <euanrussano@example.com>
License: MIT
Project-URL: Homepage, https://github.com/euanrussano/processlab
Project-URL: Repository, https://github.com/euanrussano/processlab
Project-URL: Bug Tracker, https://github.com/euanrussano/processlab/issues
Keywords: simulation,dynamical-systems,numerical-methods,ode,computational-graph
Classifier: Development Status :: 3 - Alpha
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.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.0.0
Provides-Extra: visualization
Requires-Dist: matplotlib>=3.5.0; extra == "visualization"
Provides-Extra: scientific
Requires-Dist: scipy>=1.10.0; extra == "scientific"
Requires-Dist: networkx>=3.0; extra == "scientific"
Provides-Extra: all
Requires-Dist: matplotlib>=3.5.0; extra == "all"
Requires-Dist: scipy>=1.10.0; extra == "all"
Requires-Dist: networkx>=3.0; extra == "all"
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: mypy>=1.0.0; extra == "dev"
Requires-Dist: mypy-extensions>=1.0.0; extra == "dev"
Requires-Dist: numpy-typing-compat>=20251206.0; extra == "dev"
Requires-Dist: scipy-stubs>=1.17.0; extra == "dev"
Requires-Dist: networkx-stubs>=0.0.1; extra == "dev"
Dynamic: license-file

# ProcessLab

A flexible and intuitive Python library for simulating dynamic systems using computational graphs.

## Features

- 🔢 **Node-based computational graph** for building dynamic models
- 🧮 **Multiple integration methods** (Euler, RK4, and extensible)
- 📊 **Flexible recording system** (CSV, terminal, matplotlib)
- 🎯 **Event detection** for threshold crossing and steady states
- 🔬 **Scientific computing** support with NumPy integration
- 📈 **Visualization** with matplotlib integration

## Installation

```bash
# Basic installation
pip install processlab

# With visualization support
pip install processlab[visualization]

# With all features
pip install processlab[all]
```

## Quick Start

```python
from processlab import Model, Simulation, CSVSimulationRecorder

# Create a simple exponential decay model: dx/dt = -k*x
model = Model()
k = model.constant(-0.5)
x = model.state(1.0)  # Initial value
x.set_derivative(k.multiply(x))

# Run simulation
sim = Simulation(model)
sim.add_recorder(CSVSimulationRecorder('output.csv'))
sim.run(start=0, end=10, steps=100)
```

## Example: Logistic Growth

```python
from processlab import Model, Simulation, EulerIntegrator, RK4Integrator
import matplotlib.pyplot as plt

# Create logistic growth model: dx/dt = r*x*(1 - x/K)
model = Model()
r = model.constant(0.2)   # Growth rate
K = model.constant(1.0)   # Carrying capacity
x = model.state(0.1)      # Initial population

# Build derivative: r*x*(1 - x/K)
one = model.constant(1.0)
derivative = r.multiply(x).multiply(one.sub(x.div(K)))
x.set_derivative(derivative)

# Compare integrators
sim1 = Simulation(model, dt=0.01, integrator=EulerIntegrator())
sim1.run(0, 50, 500)

sim2 = Simulation(model, dt=0.01, integrator=RK4Integrator())
sim2.run(0, 50, 500)
```

## Core Concepts

### Models and Nodes

ProcessLab uses a computational graph approach where:
- **Nodes** represent values and operations
- **States** are variables that change over time
- **Models** connect nodes together

```python
from processlab import Model
model = Model()

# Create nodes
a = model.constant(2.0)
b = model.constant(3.0)
c = a.add(b)  # c = a + b

# Create state variables
x = model.state(initial_value=1.0)
```

### Integration Methods

Choose from multiple numerical integration methods:

```python
from processlab import Simulation
from processlab import EulerIntegrator, RK4Integrator

# First-order Euler method (fast, less accurate)
sim = Simulation(model, integrator=EulerIntegrator())

# Fourth-order Runge-Kutta (slower, more accurate)
sim = Simulation(model, integrator=RK4Integrator())
```

### Event Detection

Detect when specific conditions are met during simulation:

```python
from processlab import ThresholdDetector, SteadyStateDetector

# Detect when state crosses threshold
sim.add_detector(ThresholdDetector(state_index=0, threshold=0.8))

# Detect steady state
sim.add_detector(SteadyStateDetector(state_index=0, tol=1e-6))

sim.run(0, 100, 1000)

# Check detected events
for event in sim.events:
    print(f"Event '{event.tag}' at t={event.time}")
```

### Recording Results

Multiple ways to record and visualize results:

```python
from processlab import (
    CSVSimulationRecorder,
    TerminalSimulationRecorder,
    MatplotlibRecorder
)

# Save to CSV
sim.add_recorder(CSVSimulationRecorder('results.csv'))

# Print to terminal
sim.add_recorder(TerminalSimulationRecorder(print_every=10))

# Plot with matplotlib
sim.add_recorder(MatplotlibRecorder(save_path='plot.png', show=True))

sim.run(0, 10, 100)
```

## Documentation

For more examples and detailed API documentation, visit the [documentation](https://github.com/euanrussano/processlab).

## Development

```bash
# Clone repository
git clone https://github.com/euanrussano/processlab.git
cd processlab

# Install in development mode
pip install -e ".[all,dev]"

# Run tests
pytest

# Format code
black processlab/

# Type checking
mypy processlab/
```

## Requirements

- Python >= 3.8
- NumPy >= 2.0.0
- matplotlib >= 3.5.0 (optional, for visualization)

## License

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

## Contributing

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

## Authors

- **Euan Russano** - [GitHub](https://github.com/euanrussano)

## Acknowledgments

Built with Python and the scientific Python ecosystem (NumPy, matplotlib).
