Analysis API Reference

The mechanics_dsl.analysis package provides tools for energy analysis, stability analysis, and validation of simulation results.

EnergyAnalyzer

class mechanics_dsl.analysis.EnergyAnalyzer

Energy analysis for mechanical systems. Computes kinetic energy, potential energy, and validates conservation.

Example:

from mechanics_dsl.analysis import EnergyAnalyzer
import numpy as np

analyzer = EnergyAnalyzer()

# Compute energies for pendulum
energies = analyzer.compute_pendulum_energy(
    solution, m=1.0, length=1.0, g=9.81
)

T = energies['kinetic']
V = energies['potential']
E = energies['total']

# Check conservation
result = analyzer.check_conservation(solution, T, V, tolerance=1e-3)

if result['conserved']:
    print(f"Energy conserved! Max error: {result['max_relative_error']:.2e}")
else:
    print(f"Energy drift detected: {result['max_relative_error']:.2%}")

Methods:

compute_kinetic_energy(solution, masses, velocities=None)

Compute kinetic energy T = ½mv² for each timestep.

Parameters:

• solution – Simulation result dictionary

• masses – Dict mapping coordinate names to masses

Returns:

Kinetic energy array

compute_potential_energy(solution, potential_func)

Compute potential energy at each timestep.

Parameters:

• solution – Simulation result

• potential_func – Callable V(state) → float

Returns:

Potential energy array

check_conservation(solution, kinetic, potential, tolerance=1e-3)

Check energy conservation.

Returns:

Dict with conservation analysis results:

{
    'conserved': bool,
    'initial_energy': float,
    'max_relative_error': float,
    'mean_relative_error': float,
    'total_energy': np.ndarray,
    'kinetic_energy': np.ndarray,
    'potential_energy': np.ndarray,
}

compute_pendulum_energy(solution, m, length, g)

Specialized method for simple pendulum energy.

Parameters:

• m – Mass

• length – Pendulum length

• g – Gravitational acceleration

Returns:

Dict with kinetic, potential, and total energy arrays

StabilityAnalyzer

class mechanics_dsl.analysis.StabilityAnalyzer

Stability analysis for dynamical systems. Provides linearization, eigenvalue analysis, and Lyapunov exponent estimation.

Example:

from mechanics_dsl.analysis import StabilityAnalyzer
import sympy as sp

analyzer = StabilityAnalyzer()

# Define system equations: dx/dt = f(x)
x, y = sp.symbols('x y')
equations = {
    'x_dot': y,
    'y_dot': -sp.sin(x) - 0.1*y  # Damped pendulum
}

# Find fixed points
fixed_points = analyzer.find_fixed_points(equations, [x, y])
print(f"Fixed points: {fixed_points}")

# Compute Jacobian
jacobian = analyzer.compute_jacobian(equations, [x, y])

# Analyze stability at each fixed point
for fp in fixed_points:
    result = analyzer.analyze_stability(jacobian, fp)
    print(f"At {fp}: {result['stability']}")
    print(f"  Eigenvalues: {result['eigenvalues']}")

Methods:

find_fixed_points(equations, variables)

Find fixed points where all derivatives are zero.

Parameters:

• equations – Dict mapping derivative names to expressions

• variables – List of state variable symbols

Returns:

List of fixed point dictionaries

compute_jacobian(equations, variables)

Compute the Jacobian matrix of the system.

Parameters:

• equations – Dict mapping outputs to expressions

• variables – List of input variable symbols

Returns:

SymPy Matrix (Jacobian)

analyze_stability(jacobian, fixed_point)

Analyze stability at a fixed point via eigenvalues.

Returns:

Dict with stability analysis:

{
    'eigenvalues': list,    # Complex eigenvalues
    'max_real_part': float, # Largest real part
    'stability': str,       # 'stable', 'unstable', or 'marginally_stable'
    'jacobian': Matrix,     # Evaluated Jacobian
}

estimate_lyapunov_exponent(trajectory, dt, n_renorm=100)

Estimate largest Lyapunov exponent from trajectory data.

Parameters:

• trajectory – State array (n_vars × n_points)

• dt – Time step

• n_renorm – Number of renormalization steps

Returns:

Estimated Lyapunov exponent (float)

Note

Positive Lyapunov exponent indicates chaotic behavior.

Stability Types

The stability analyzer classifies fixed points as:

Type	Condition
stable	All eigenvalues have negative real parts
unstable	At least one eigenvalue has positive real part
marginally_stable	All eigenvalues have non-positive real parts, at least one is zero
center	All eigenvalues are purely imaginary (oscillatory)

For 2D systems, fixed points can be further classified:

• Stable node: Both eigenvalues real and negative

• Unstable node: Both eigenvalues real and positive

• Saddle: One positive, one negative real eigenvalue

• Spiral (stable): Complex eigenvalues with negative real part

• Spiral (unstable): Complex eigenvalues with positive real part

• Center: Pure imaginary eigenvalues