Defining Dynamical Systems

This guide demonstrates how to define and simulate a Dynamical System using TVBO’s specification language.

Example: Damped Pendulum

We’ll create a simple damped pendulum system to illustrate the key concepts.

System Specification

Define the pendulum Dynamics using YAML format with Parameters, state variables, and output transforms:

import yaml
from tvbo import Dynamics, SimulationExperiment

# Pendulum System
dynamics_yaml = """
name: PendulumSystem
description: A simple damped pendulum system for demonstrating TVBO capabilities.
parameters:
    c:
        description: Damping coefficient
        value: 0.001
        unit: 1/ms
    omega0:
        description: Natural frequency
        value: 0.01
        unit: rad/ms
    L:
        description: Length of the pendulum
        unit: m
        value: 1.0
state_variables:
    theta:
        description: Angle of the pendulum
        unit: rad
        initial_value: 1.0
        equation:
            rhs: omega
    omega:
        description: Angular velocity
        unit: rad/ms
        initial_value: 0.0
        equation:
            rhs: -c*omega - omega0**2 * sin(theta)
derived_variables:
    x:
        description: X coordinate of the pendulum bob
        unit: m
        equation:
            rhs: L * sin(theta)
    y:
        description: Y coordinate of the pendulum bob
        unit: m
        equation:
            rhs: -L * cos(theta)
output: 
    - x
    - y
"""

pendulum = SimulationExperiment(
    dynamics=Dynamics(**yaml.load(dynamics_yaml, Loader=yaml.FullLoader)),
)
results = pendulum.run(duration=5_000)

The system consists of: - Parameters: Physical constants (damping, frequency, length) - State variables: Time-evolving quantities (angle θ, angular velocity ω) - Output transforms: Computed observables (Cartesian coordinates x, y)

Visualization

Real-time animation of the pendulum motion alongside the time series data: