Analysis Package

The analysis package provides comprehensive tools for process control system analysis, including transfer functions, system analysis, and model identification.

Note

This is part of the modern modular structure of SPROCLIB.

Submodules

Transfer Function

Transfer Function Analysis for SPROCLIB

This module provides transfer function representation and frequency domain analysis for linear time-invariant systems in process control applications.

Author: Thorsten Gressling <gressling@paramus.ai> License: MIT License

class sproclib.analysis.transfer_function.TransferFunction(num, den, name='G(s)')[source]

Bases: object

Transfer function representation and analysis.

Parameters:

num (List[float] | <MagicMock id='130137681096928'>)
den (List[float] | <MagicMock id='130137681097936'>)
name (str)

__init__(num, den, name='G(s)')[source]

Initialize transfer function G(s) = num(s)/den(s).

Parameters:

num (List[float] | <MagicMock id='130137681096928'>) – Numerator coefficients (highest order first)
den (List[float] | <MagicMock id='130137681097936'>) – Denominator coefficients (highest order first)
name (str) – Transfer function name

classmethod first_order_plus_dead_time(K, tau, theta, name='FOPDT')[source]

Create first-order plus dead time transfer function. G(s) = K * exp(-theta*s) / (tau*s + 1)

Parameters:

K (float) – Process gain
tau (float) – Time constant
theta (float) – Dead time
name (str) – Transfer function name

Returns:

TransferFunction object (without dead time for analysis)

Return type:

TransferFunction

classmethod second_order(K, zeta, wn, name='Second Order')[source]

Create second-order transfer function. G(s) = K * wn² / (s² + 2*zeta*wn*s + wn²)

Parameters:

K (float) – Process gain
zeta (float) – Damping ratio
wn (float) – Natural frequency
name (str) – Transfer function name

Returns:

TransferFunction object

Return type:

TransferFunction

step_response(t=None, t_final=10.0, input_magnitude=1.0)[source]

Calculate step response.

Parameters:

t (<MagicMock id='130137681098944'> | None) – Time vector (optional)
t_final (float) – Final time if t not provided
input_magnitude (float) – Step magnitude

Returns:

Dictionary with ‘t’ and ‘y’ arrays

Return type:

Dict[str, <MagicMock id=’130137681095584’>]

bode_plot(w=None, plot=True)[source]

Generate Bode plot data.

Parameters:

w (<MagicMock id='130137681094240'> | None) – Frequency vector (optional)
plot (bool) – Whether to create plot

Returns:

Dictionary with frequency, magnitude, and phase data

Return type:

Dict[str, <MagicMock id=’130137681087184’>]

poles_zeros()[source]

Get poles and zeros of transfer function.

Return type:: Dict[str, <MagicMock id=’130137681099280’>]

stability_analysis()[source]

Analyze system stability.

Return type:: Dict[str, Any]

frequency_response(w)[source]

Calculate frequency response.

Parameters:: w (<MagicMock id='130137681100288'>) – Frequency vector [rad/s]
Returns:: Tuple of (magnitude, phase, frequency)
Return type:: Tuple[<MagicMock id=’130137681674320’>, <MagicMock id=’130137681674656’>, <MagicMock id=’130137681674992’>]

impulse_response(t=None, t_final=10.0)[source]

Calculate impulse response.

Parameters:

t (<MagicMock id='130137681677344'> | None) – Time vector (optional)
t_final (float) – Final time if t not provided

Returns:

Dictionary with ‘t’ and ‘y’ arrays

Return type:

Dict[str, <MagicMock id=’130137681678352’>]

System Analysis

System Analysis for SPROCLIB

This module provides comprehensive system analysis tools including stability analysis, controllability/observability tests, and performance metrics.

Author: Thorsten Gressling <gressling@paramus.ai> License: MIT License

class sproclib.analysis.system_analysis.SystemAnalysis(name='System Analysis')[source]

Bases: object

Comprehensive system analysis tools.

Parameters:: name (str)

__init__(name='System Analysis')[source]

Initialize system analysis.

Parameters:: name (str) – Analysis name

stability_analysis(A, system_name='System')[source]

Analyze stability of linear system dx/dt = A*x.

Parameters:

A (<MagicMock id='130137681683056'>) – State matrix
system_name (str) – System name for reporting

Returns:

Dictionary with stability analysis results

Return type:

Dict[str, Any]

controllability_analysis(A, B)[source]

Analyze controllability of system (A, B).

Parameters:

A (<MagicMock id='130137681683392'>) – State matrix [n x n]
B (<MagicMock id='130137681683728'>) – Input matrix [n x m]

Returns:

Dictionary with controllability results

Return type:

Dict[str, Any]

observability_analysis(A, C)[source]

Analyze observability of system (A, C).

Parameters:

A (<MagicMock id='130137681684064'>) – State matrix [n x n]
C (<MagicMock id='130137681684400'>) – Output matrix [p x n]

Returns:

Dictionary with observability results

Return type:

Dict[str, Any]

disturbance_rejection_analysis(plant_tf, controller_tf, disturbance_type='step', w=None)[source]

Analyze disturbance rejection performance.

Parameters:

plant_tf (Tuple[<MagicMock id='130137681684736'>, <MagicMock id='130137681685072'>]) – Plant transfer function (num, den)
controller_tf (Tuple[<MagicMock id='130137681686752'>, <MagicMock id='130137681687088'>]) – Controller transfer function (num, den)
disturbance_type (str) – Type of disturbance (‘step’, ‘frequency’)
w (<MagicMock id='130137681681712'> | None) – Frequency vector for analysis

Returns:

Dictionary with disturbance rejection analysis

Return type:

Dict[str, Any]

performance_metrics(t, y, setpoint=1.0)[source]

Calculate standard performance metrics for step response.

Parameters:

t (<MagicMock id='130137681688096'>) – Time array
y (<MagicMock id='130137681688432'>) – Response array
setpoint (float) – Target setpoint value

Returns:

Dictionary with performance metrics

Return type:

Dict[str, float]

linearization_analysis(model_func, x_ss, u_ss, epsilon=1e-06)[source]

Linearize a nonlinear model and analyze the linear approximation.

Parameters:

model_func (callable) – Function f(x, u) returning dx/dt
x_ss (<MagicMock id='130137681688768'>) – Steady-state states
u_ss (<MagicMock id='130137681689104'>) – Steady-state inputs
epsilon (float) – Perturbation size for finite differences

Returns:

Dictionary with linearization results

Return type:

Dict[str, <MagicMock id=’130137681689440’>]

sproclib.analysis.system_analysis.step_response(system, t=None, t_final=10.0, input_magnitude=1.0)[source]

Calculate step response of a system.

Parameters:

system – Transfer function object or (num, den) tuple
t (<MagicMock id='130137680232528'> | None) – Time vector (optional)
t_final (float) – Final time if t not provided
input_magnitude (float) – Step magnitude

Returns:

Dictionary with ‘t’ and ‘y’ arrays

Return type:

Dict[str, <MagicMock id=’130137680233536’>]

sproclib.analysis.system_analysis.bode_plot(system, w=None, plot=True, title='Bode Plot')[source]

Generate Bode plot for frequency response analysis.

Parameters:

system – Transfer function object or (num, den) tuple
w (<MagicMock id='130137680234544'> | None) – Frequency vector (optional)
plot (bool) – Whether to create plot
title (str) – Plot title

Returns:

Dictionary with frequency, magnitude, and phase data

Return type:

Dict[str, <MagicMock id=’130137680235552’>]

sproclib.analysis.system_analysis.stability_analysis(A, system_name='System')[source]

Analyze stability of linear system dx/dt = A*x.

Parameters:

A (<MagicMock id='130137680236560'>) – State matrix
system_name (str) – System name for reporting

Returns:

Dictionary with stability analysis results

Return type:

Dict[str, Any]

Model Identification

Model Identification for SPROCLIB

This module provides tools for system identification and model fitting from experimental data or step response tests.

Author: Thorsten Gressling <gressling@paramus.ai> License: MIT License

class sproclib.analysis.model_identification.ModelIdentification(name='Model Identification')[source]

Bases: object

System identification and model fitting tools.

Parameters:: name (str)

__init__(name='Model Identification')[source]

Initialize model identification.

Parameters:: name (str) – Identification name

fit_fopdt(t_data, y_data, step_magnitude=1.0, initial_guess=None)[source]

Fit First Order Plus Dead Time model to step response data.

Parameters:

t_data (<MagicMock id='130137680240928'>) – Time data
y_data (<MagicMock id='130137681680704'>) – Response data
step_magnitude (float) – Magnitude of step input
initial_guess (Tuple[float, float, float] | None) – Initial parameter guess (K, tau, theta)

Returns:

Dictionary with fitted parameters and metrics

Return type:

Dict[str, Any]

fit_sopdt(t_data, y_data, step_magnitude=1.0, initial_guess=None)[source]

Fit Second Order Plus Dead Time model to step response data.

Parameters:

t_data (<MagicMock id='130137681680368'>) – Time data
y_data (<MagicMock id='130137681093904'>) – Response data
step_magnitude (float) – Magnitude of step input
initial_guess (Tuple[float, float, float, float] | None) – Initial parameter guess (K, tau1, tau2, theta)

Returns:

Dictionary with fitted parameters and metrics

Return type:

Dict[str, Any]

fit_transfer_function(freq_data, magnitude_data, phase_data, model_order=(2, 2))[source]

Fit transfer function to frequency response data.

Parameters:

freq_data (<MagicMock id='130137681090544'>) – Frequency data [rad/s]
magnitude_data (<MagicMock id='130137681093232'>) – Magnitude data (linear scale)
phase_data (<MagicMock id='130137681092896'>) – Phase data [radians]
model_order (Tuple[int, int]) – Transfer function order (numerator, denominator)

Returns:

Dictionary with fitted transfer function

Return type:

Dict[str, Any]

validate_model(model_params, validation_data, model_type='fopdt')[source]

Validate fitted model against independent validation data.

Parameters:

model_params (Dict[str, float]) – Fitted model parameters
validation_data (Dict[str, <MagicMock id='130137682638032'>]) – Dictionary with ‘t’ and ‘y’ arrays
model_type (str) – Type of model (‘fopdt’, ‘sopdt’)

Returns:

Dictionary with validation metrics

Return type:

Dict[str, float]

sproclib.analysis.model_identification.fit_fopdt(t_data, y_data, step_magnitude=1.0, initial_guess=None)[source]

Fit First Order Plus Dead Time model to step response data.

Parameters:

t_data (<MagicMock id='130137680240256'>) – Time data
y_data (<MagicMock id='130137680239920'>) – Response data
step_magnitude (float) – Magnitude of step input
initial_guess (Tuple[float, float, float] | None) – Initial parameter guess (K, tau, theta)

Returns:

Dictionary with fitted parameters and metrics

Return type:

Dict[str, float]

Quick Usage

Transfer Function Analysis:

from analysis.transfer_function import TransferFunction
from analysis.system_analysis import step_response, bode_plot

# Create a transfer function
tf = TransferFunction([1], [1, 1], name="First Order")

# Analyze step response
response = step_response(tf)

# Generate Bode plot
bode_data = bode_plot(tf, plot=True)

Model Identification:

from analysis.model_identification import fit_fopdt
import numpy as np

# Generate sample data
t = np.linspace(0, 20, 100)
y = 2 * (1 - np.exp(-t/3))  # FOPDT response

# Fit FOPDT model
result = fit_fopdt(t, y)
print(f"K={result['K']:.2f}, tau={result['tau']:.2f}")