Metadata-Version: 2.4
Name: opensmc
Version: 2.0.0
Summary: A modular sliding mode control toolbox for Python
Author-email: Ali Al Ghanimi <ali.alghanimi@uokufa.edu.iq>
License: MIT
Project-URL: Homepage, https://github.com/Balghanimi/OpenSMC
Project-URL: Documentation, https://github.com/Balghanimi/OpenSMC
Project-URL: Repository, https://github.com/Balghanimi/OpenSMC
Keywords: sliding-mode-control,SMC,control-systems,robotics,HOSMC
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.21
Provides-Extra: rl
Requires-Dist: gymnasium>=0.29; extra == "rl"
Requires-Dist: stable-baselines3>=2.0; extra == "rl"
Requires-Dist: torch>=2.0; extra == "rl"
Provides-Extra: viz
Requires-Dist: matplotlib>=3.5; extra == "viz"
Provides-Extra: all
Requires-Dist: opensmc[rl,viz]; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: opensmc[all]; extra == "dev"

# OpenSMC — Sliding Mode Control for Python

**The first and only `pip install`-able sliding mode control toolbox.**

11 surfaces | 5 reaching laws | 9 plants | 17 controllers | 7 estimators | 5 Gymnasium environments

[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org)
[![SoftwareX](https://img.shields.io/badge/SoftwareX-submitted-orange.svg)](https://doi.org/10.5281/zenodo.19029180)

## Install

```bash
pip install opensmc             # Core (numpy only)
pip install opensmc[viz]        # + matplotlib
pip install opensmc[rl]         # + gymnasium + stable-baselines3
pip install opensmc[all]        # Everything
```

## Quick Start — 6 Lines

```python
import numpy as np
from opensmc.surfaces import LinearSurface
from opensmc.reaching import SuperTwisting
from opensmc.controllers import ClassicalSMC
from opensmc.plants import DoubleIntegrator
from opensmc.simulator import Simulator
from opensmc import metrics

ctrl = ClassicalSMC(surface=LinearSurface(c=10), reaching=SuperTwisting(k1=15, k2=10))
result = Simulator(dt=1e-4, T=5.0).run(ctrl, DoubleIntegrator(),
                                         ref_fn=lambda t: np.array([1.0, 0.0]))
print(f"RMSE: {metrics.rmse(result):.4f}, Settling: {metrics.settling_time(result):.3f}s")
```

## Why OpenSMC?

**Before OpenSMC:** Every SMC paper reimplements controllers from scratch. No standard benchmarks. No way to compare methods fairly.

**After OpenSMC:** Swap any surface, reaching law, or plant with a one-line change. Compare 15 controllers on 9 plants with standardized metrics. Bridge SMC with reinforcement learning via Gymnasium.

```
Surface × Reaching Law × Plant × Estimator = Controller
  (11)       (5)          (9)      (7)
```

**Zero competitors.** No other Python SMC package exists on PyPI or GitHub.

## Components

### Sliding Surfaces (11)

| Surface | Type | Key Property |
|---------|------|-------------|
| `LinearSurface` | Linear | Asymptotic convergence |
| `TerminalSurface` | Terminal | Finite-time convergence |
| `NonsingularTerminalSurface` | Nonsingular | Singularity-free finite-time |
| `FastTerminalSurface` | Fast Terminal | Fast + finite-time |
| `IntegralTerminalSurface` | Integral Terminal | Integral compensation |
| `IntegralSlidingSurface` | Integral | Eliminates reaching phase |
| `PIDSurface` | PID-like | PID action on sliding surface |
| `HierarchicalSurface` | Hierarchical | For underactuated systems |
| `NonlinearDampingSurface` | Nonlinear Damping | Enhanced stability margin |
| `GlobalSurface` | Global | No reaching phase, no overshoot |
| `PredefinedTimeSurface` | Predefined-Time | User-set convergence time |

### Reaching Laws (5)

| Reaching Law | Continuity | Chattering |
|-------------|-----------|-----------|
| `ConstantRate` | Discontinuous | Yes |
| `ExponentialRate` | Discontinuous | Reduced |
| `PowerRate` | Discontinuous | Reduced |
| `SuperTwisting` | **Continuous** | **No** |
| `Saturation` | Continuous | **No** |

### Plants (9)

| Plant | States | Inputs | DOF | Underactuated |
|-------|--------|--------|-----|---------------|
| `DoubleIntegrator` | 2 | 1 | 1 | No |
| `InvertedPendulum` | 4 | 1 | 2 | Yes |
| `SinglePendulumCrane` | 4 | 1 | 2 | Yes |
| `DoublePendulumCrane` | 6 | 1 | 3 | Yes |
| `Quadrotor6DOF` | 12 | 4 | 6 | Yes |
| `DualStageNanopositioner` | 4 | 1 | 2 | No |
| `TwoLinkArm` | 4 | 2 | 2 | No |
| `PMSM` | 4 | 2 | 2 | No |
| `SurfaceVessel` | 6 | 3 | 3 | No |

### Controllers (17)

| Controller | Type | Reference |
|-----------|------|-----------|
| `ClassicalSMC` | Generic | Utkin (1977) |
| `AdaptiveSMC` | Adaptive gain | Liu & Wang (2013) |
| `DynamicSMC` | Dynamic | Liu & Wang (2013) |
| `AggregatedHSMC` | Hierarchical | Qian & Yi (2015) |
| `IncrementalHSMC` | Hierarchical | Qian & Yi (2015) |
| `CombiningHSMC` | Hierarchical | Qian & Yi (2015) |
| `DiscreteSMC` | Discrete-time | Gao (1995) |
| `FixedTimeSMC` | Fixed-time | Polyakov (2012) |
| `FuzzySMC` | Fuzzy logic | Khanesar (2021) |
| `ITSMC` | Learning-based | Al Ghanimi (2026) |
| `NFTSMC` | Finite-time | Al Ghanimi (2026) |
| `TwistingSMC` | 2nd-order HOSMC | Levant (1993) |
| `QuasiContinuous2SMC` | Quasi-continuous | Levant (2005) |
| `NestedHOSMC` | Arbitrary-order | Levant (2003) |
| `QuasiContinuousHOSMC` | Arbitrary-order | Levant (2005) |
| `PID` | Baseline | — |
| `LQR` | Baseline | — |

### Estimators (7)

`NoEstimator` · `DisturbanceObserver` · `ExtendedStateObserver` · `HighGainObserver` · `IntegralChainDifferentiator` · `LevantDifferentiator` · `RBF_ELM`

## Gymnasium Environments

5 RL-ready environments, compatible with Stable-Baselines3:

```python
import gymnasium as gym
import opensmc  # registers environments

env = gym.make("OpenSMC/DoubleIntegrator-v0")    # 2 states, 1 input
env = gym.make("OpenSMC/InvertedPendulum-v0")    # 4 states, 1 input
env = gym.make("OpenSMC/Crane-v0")               # 4 states, 1 input
env = gym.make("OpenSMC/Quadrotor-v0")            # 12 states, 4 inputs
env = gym.make("OpenSMC/PMSM-v0")                # 5 obs (4 states + ref), 2 inputs
```

### Train an RL controller in 3 lines

```python
from stable_baselines3 import PPO
env = gym.make("OpenSMC/DoubleIntegrator-v0", disturbance=1.0)
model = PPO("MlpPolicy", env).learn(50_000)
```

### Use RL as a sliding surface

```python
from opensmc.rl import RLDiscoveredSurface
surface = RLDiscoveredSurface("my_trained_model")
ctrl = ClassicalSMC(surface=surface, reaching=SuperTwisting(k1=15, k2=10))
```

## Benchmarking

Compare any controllers on any plant with standardized metrics:

```python
from opensmc import metrics

# 12 metrics: rmse, mae, ise, iae, settling_time, overshoot,
#             rise_time, control_effort, chattering_index,
#             reaching_time, steady_state_error, energy_efficiency
```

## Modularity — The Core Idea

Every component is interchangeable. Mix any surface with any reaching law:

```python
from opensmc.surfaces import TerminalSurface, FastTerminalSurface
from opensmc.reaching import SuperTwisting, ConstantRate
from opensmc.controllers import ClassicalSMC

# Same controller class, different behaviors:
ctrl_a = ClassicalSMC(surface=TerminalSurface(), reaching=SuperTwisting())
ctrl_b = ClassicalSMC(surface=FastTerminalSurface(), reaching=ConstantRate())
```

## Citation

If you use OpenSMC in your research, please cite:

```bibtex
@article{alghanimi2026opensmc,
  title   = {OpenSMC: A Modular Open-Source Sliding Mode Control Toolbox},
  author  = {Al Ghanimi, Ali},
  journal = {SoftwareX},
  year    = {2026},
  doi     = {10.5281/zenodo.19029180},
  note    = {Under review}
}
```

## License

MIT License. See [LICENSE](LICENSE) for details.
