Metadata-Version: 2.4
Name: asim
Version: 26.3.2
Summary: Automatic simulation system powered by neural networks
Keywords: simulation
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.8.0
Requires-Dist: lightning>=2.5.5
Requires-Dist: casadi>=3.7.2
Provides-Extra: dev
Requires-Dist: matplotlib; extra == "dev"
Dynamic: license-file

# asim — Neural Network Simulation & Optimal Control for Physical Systems

**asim** is a Python library for modeling, simulating, and optimizing physical systems using neural networks. It is designed for industrial process control — such as boilers, cooling systems, and heat exchangers — where data-driven state-space models replace first-principles equations.

## Installation

```bash
pip install asim
```

## What is asim

Train a neural network on historical sensor data, export it to ONNX, then run closed-loop simulation or gradient-based optimal control — all within a unified API.

- **Data-driven state-space modeling** — learns system dynamics from tabular time-series data with explicit separation of controllable inputs (`Vu`), state variables (`Vx`), and time-varying parameters (`Vc`)
- **Automatic normalization** — columns sharing a physical unit (`union=`) are scaled together; scalers are baked into the ONNX export
- **ONNX simulation** — autoregressive rollout via `onnxruntime`; supports multi-group systems with cross-group wiring
- **Optimal control** — `OffPolicyOptimizer` translates the ONNX graph into CasADi symbolic math and solves step-by-step MPC problems with IPOPT
- **Monotonicity checking** — `Explainer` verifies gradient sign constraints to catch physically implausible model behavior

## Using asim

```python
import matplotlib.pyplot as plt
import pandas as pd
from asim import Vt, Vu, Vx
from asim.dataset import PhysicalDataManage
from asim.explainer import Explainer
from asim.model import PhysicalFieldModel
from asim.optimizer import OffPolicyOptimizer
from asim.simulator import PhysicalSimulator
from asim.tool import DummyDatasets

# 1. Define data and structure
df = DummyDatasets.boiler_minimum(size=10000)  # pd.read_csv("demo.csv")
cols = [
    Vt(label="ts"),
    Vu(group="boiler", label="heat_power1", minmax=(1.0, None), union="kw"),
    Vu(group="boiler", label="heat_power2", minmax=(None, 90), union="kw"),
    Vx(group="boiler", label="heat_temp", union="kj"),
]
dm = PhysicalDataManage(df, columns=cols, batch_size=64, seq_size=5)

# 2A. Select the model, define the parameters, train and save
fm = PhysicalFieldModel(dm, lr=0.002)
fm.fit(epochs=50)
fm.export("demo.sim.onnx")

# 2B. Check model
explainer = Explainer(dm, fm)
explainer.checkGrad()

# 2C. Use a simulator to simulate the operation
sim = PhysicalSimulator("demo.sim.onnx", dm=dm)
sim_df = df[0:1440].copy()
sim_df.index = pd.to_datetime(sim_df["ts"], unit="s", utc=True).dt.tz_convert("Etc/GMT-8")
sim_df = sim.steps(sim_df, x0={"heat_temp": sim_df["heat_temp"].iloc[0]})
sim.plots(sim_df)
plt.show()

# 3A. Build the optimizer
lTerm = lambda x, u, p: (x - p) ** 2 + 0.5 * (u[0] ** 2 + u[1] ** 2)
mTerm = lambda x, u, p: (x - p) ** 2
opt = OffPolicyOptimizer("demo.sim.onnx", dm=dm, lTerm=lTerm, mTerm=mTerm)
opt.fit(epochs=100)
opt.export("demo.opt.onnx")

# 3B. Use the optimizer
opt_df = opt.steps(df[0:360].copy(), interval=1)
opt.plots(opt_df)
plt.show()
```
