tf2ss 1.0.0

Transfer Function to State Space conversion for MIMO systems

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 with 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:

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:

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:

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:

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)

pip install tf2ss

From Source with UV

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

Development Installation

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

Alternatively, you can use pip for development:

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:

uv run pytest

Run tests with coverage:

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

Run specific test categories:

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 file for details.

🔗 Related Projects

• Python Control: Control systems library for Python
• SLYCOT: Python wrapper for SLICOT control library
• SIPPY: Systems Identification Package for Python

📚 Citation

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

@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 on GitHub
• Check the existing documentation and examples
• Review the test cases for usage patterns