Metadata-Version: 2.4
Name: tf2ss
Version: 1.0.0
Summary: Transfer Function to State Space conversion for MIMO systems
Project-URL: repository, https://github.com/MarekWadinger/tf2ss
Project-URL: documentation, https://github.com/MarekWadinger/tf2ss#readme
Project-URL: issues, https://github.com/MarekWadinger/tf2ss/issues
Author-email: Marek Wadinger <marek.wadinger@example.com>
License: MIT
License-File: LICENSE
Keywords: MIMO,control systems,state space,system identification,transfer function
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Requires-Dist: control<1.0.0,>=0.9.0
Requires-Dist: numpy<3.0.0,>=1.20.0
Requires-Dist: scipy<2.0.0,>=1.7.0
Requires-Dist: sympy<2.0.0,>=1.8
Description-Content-Type: text/markdown

# tf2ss

[![PyPI Package latest release](https://img.shields.io/pypi/v/tf2ss.svg?style=)](https://pypi.org/project/tf2ss/)
[![Supported versions](https://img.shields.io/pypi/pyversions/tf2ss.svg?style=)](https://pypi.org/project/tf2ss/)
[![Quality and Tests](https://github.com/MarekWadinger/tf2ss/actions/workflows/ci.yml/badge.svg)](https://github.com/MarekWadinger/tf2ss/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/MarekWadinger/tf2ss/branch/main/graph/badge.svg)](https://codecov.io/gh/MarekWadinger/tf2ss)

## Transfer Function to State-Space Conversion for MIMO Systems

`tf2ss` is a Python library for converting transfer function representations to state-space form, supporting **Multi-Input Multi-Output (MIMO) systems**! Unlike [control](https://github.com/python-control/python-control) with [SLYCOT](https://github.com/python-control/Slycot) which requires a Fortran compiler and is often challenging to install, `tf2ss` is a pure Python implementation that produces results consistent with MATLAB without any compilation dependencies.

| Library | Installation Complexity | Dependencies        | MATLAB Consistency | MIMO Support |
|---------|-------------------------|---------------------|--------------------|--------------|
| tf2ss   | Simple (`pip install`)  | None                | ✅                 | ✅           |
| SLYCOT  | Complex (requires Fortran) | Fortran, BLAS    | ❌                 | ✅           |
| scipy   | Simple (`pip install`)  | None                | ✅                 | ❌           |

## ⚡️ Quickstart

Convert a simple SISO transfer function to state-space:

```python
from tf2ss import tf2ss

# Simple SISO system: H(s) = (s+1)/(s^2+3s+2)
numerators = [[[1, 1]]]  # s + 1
denominators = [[[1, 3, 2]]]  # s^2 + 3s + 2

A, B, C, D = tf2ss(numerators, denominators)
print(f"A matrix:\n{A}")
print(f"B matrix:\n{B}")
print(f"C matrix:\n{C}")
print(f"D matrix:\n{D}")
```

Convert a MIMO system:

```python
from tf2ss import tf2ss
import numpy as np

# 2x2 MIMO system
numerators = [
    [[1, 0], [0.5, 1]],      # First row: [s/(s+2), (0.5s+1)/(s+2)]
    [[2], [1, 1]]            # Second row: [2/(s+2), (s+1)/(s+2)]
]
denominators = [
    [[1, 2], [1, 2]],        # Common denominator s+2
    [[1, 2], [1, 2]]
]

A, B, C, D = tf2ss(numerators, denominators)

# The resulting state-space matrices represent the MIMO system
print(f"System order: {A.shape[0]}")
print(f"Number of inputs: {B.shape[1]}")
print(f"Number of outputs: {C.shape[0]}")
```

You can also work directly with `control` library objects:

```python
import control as ctrl
from tf2ss import tf2ss

# Create transfer function using control library
sys_tf = ctrl.tf([1, 1], [1, 3, 2])
A, B, C, D = tf2ss(sys_tf)

# Create equivalent state-space system
sys_ss = ctrl.StateSpace(A, B, C, D)
```

## 🔧 Features

### Core Functionality

- **MIMO Support**: Full support for Multi-Input Multi-Output systems
- **Minimal Realization**: Optional minimal realization to reduce system order
- **Numerical Stability**: Robust algorithms for numerical computation
- **Control Integration**: Seamless integration with Python Control library

### Advanced Features

- **Common Denominator**: Automatic computation of least common multiple for denominators
- **Pole Preservation**: Maintains system poles accurately
- **Zero Preservation**: Preserves transmission zeros when possible
- **Flexible Input Formats**: Accepts both coefficient lists and control library objects

### Time Response Analysis

The package includes `forced_response` function for time-domain analysis:

```python
from tf2ss import tf2ss, forced_response
import numpy as np

# Convert to state-space
A, B, C, D = tf2ss(numerators, denominators)

# Generate time response
t = np.linspace(0, 10, 1000)
u = np.ones((1, len(t)))  # Step input
result = forced_response((A, B, C, D), t, u)

# Plot results
import matplotlib.pyplot as plt
plt.figure()
plt.plot(result.time, result.outputs[0])
plt.xlabel('Time [s]')
plt.ylabel('Output')
plt.title('Step Response')
plt.grid(True)
plt.show()
```

## 🛠 Installation

Requires Python 3.10 or higher.

### From PyPI (recommended)

```bash
pip install tf2ss
```

### From Source with UV

```bash
git clone https://github.com/MarekWadinger/tf2ss.git
cd tf2ss
uv sync
```

### Development Installation

```bash
git clone https://github.com/MarekWadinger/tf2ss.git
cd tf2ss
uv sync --all-extras
```

Alternatively, you can use pip for development:

```bash
git clone https://github.com/MarekWadinger/tf2ss.git
cd tf2ss
pip install -e .[dev]
```

## 📖 Documentation

### Mathematical Background

The conversion from transfer function to state-space follows these key steps:

1. **Common Denominator Computation**: For MIMO systems, compute the least common multiple (LCM) of all denominators
2. **Numerator Adjustment**: Adjust numerators based on the common denominator
3. **Controllable Canonical Form**: Construct state matrices in controllable canonical form
4. **Minimal Realization**: Optionally reduce to minimal form

### API Reference

#### `tf2ss(numerators, denominators, *, minreal=True)`

Convert transfer function to state-space representation.

**Parameters:**

- `numerators`: List of lists of lists containing numerator coefficients
- `denominators`: List of lists of lists containing denominator coefficients  
- `minreal`: Boolean, whether to compute minimal realization (default: True)

**Returns:**

- `A, B, C, D`: State-space matrices as numpy arrays

#### `forced_response(system, T, U, X0=0.0, **kwargs)`

Compute forced response of state-space system.

**Parameters:**

- `system`: State-space system (A, B, C, D) or TransferFunction
- `T`: Time vector
- `U`: Input array
- `X0`: Initial conditions (default: 0)

**Returns:**

- Time response data object with time, outputs, states, and inputs

## 🧪 Testing

Run the full test suite:

```bash
uv run pytest
```

Run tests with coverage:

```bash
uv run pytest --cov=tf2ss --cov-report=html
```

Run specific test categories:

```bash
uv run pytest -m "not slow"  # Skip slow tests
```

The test suite includes:

- Comparison with SLYCOT implementations
- Verification against MATLAB results
- MIMO system validation
- Numerical accuracy tests

## 🔬 Algorithm Validation

The library has been extensively validated against:

- **SLYCOT**: Industry-standard control library
- **MATLAB Control System Toolbox**: Reference implementation
- **Analytical Solutions**: Known theoretical results

See `tf2ss_report.md` for detailed comparison results.

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

### Development Setup

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Install development dependencies (`uv sync --all-extras`)
4. Make your changes
5. Run tests (`uv run pytest`)
6. Run linting (`uv run ruff check .`)
7. Commit your changes (`git commit -m 'Add some amazing feature'`)
8. Push to the branch (`git push origin feature/amazing-feature`)
9. Open a Pull Request

## 📄 License

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

## 🔗 Related Projects

- [Python Control](https://github.com/python-control/python-control): Control systems library for Python
- [SLYCOT](https://github.com/python-control/Slycot): Python wrapper for SLICOT control library
- [SIPPY](https://github.com/CPCLAB-UNIPI/SIPPY): Systems Identification Package for Python

## 📚 Citation

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

```bibtex
@software{tf2ss,
  title = {tf2ss: Transfer Function to State-Space Conversion for MIMO Systems},
  author = {Wadinger, Marek},
  url = {https://github.com/MarekWadinger/tf2ss},
  year = {2024}
}
```

## 📞 Support

If you encounter any issues or have questions:

- Open an [issue](https://github.com/MarekWadinger/tf2ss/issues) on GitHub
- Check the existing documentation and examples
- Review the test cases for usage patterns
