pygeoinf.data_assimilation.pendulum.single package

Submodules

pygeoinf.data_assimilation.pendulum.single.physics module

physics.py

Hamiltonian dynamics, coordinate transformations, and linearised models specifically for the Single Pendulum (2D state space).

pygeoinf.data_assimilation.pendulum.single.physics.eom(t: float, y: ndarray, L: float = 1.0, m: float = 1.0, g: float = 1.0) → List[float]

Hamilton’s Equations of Motion for a single pendulum.

State vector y = [theta, p_theta]

Parameters:

• t – Time (unused in autonomous system).

• y – State vector [angle, momentum].

• L – Physical parameters.

• m – Physical parameters.

• g – Physical parameters.

Returns:

[d(theta)/dt, d(p_theta)/dt]

Return type:

dydt

pygeoinf.data_assimilation.pendulum.single.physics.eom_linear(t: float, y: ndarray, L: float = 1.0, m: float = 1.0, g: float = 1.0) → ndarray

Linearised EOM around the stable equilibrium (theta=0, p=0).

pygeoinf.data_assimilation.pendulum.single.physics.eom_tangent_linear(t: float, state_aug: ndarray, L: float = 1.0, m: float = 1.0, g: float = 1.0) → ndarray

Coupled ODE for the reference trajectory AND the tangent linear perturbation. Crucial for Extended Kalman Filters (EKF).

State vector (4D): [theta, p, delta_theta, delta_p]

pygeoinf.data_assimilation.pendulum.single.physics.get_coords(theta: float | ndarray, L: float = 1.0) → Tuple[float | ndarray, float | ndarray]

Converts angular state to Cartesian coordinates for visualisation. Standard pendulum convention: 0 is down.

pygeoinf.data_assimilation.pendulum.single.physics.get_jacobian(theta: float, L: float = 1.0, m: float = 1.0, g: float = 1.0) → ndarray

Computes the Jacobian matrix J(theta) of the system at a specific state.

Returns:

2x2 Matrix J

pygeoinf.data_assimilation.pendulum.single.physics.get_linear_propagator(t: float, L: float = 1.0, m: float = 1.0, g: float = 1.0) → ndarray

Returns the analytical propagator matrix P(t) for the linear system. y(t) = P(t) @ y(0)

pygeoinf.data_assimilation.pendulum.single.visualisation module

visualisation.py

Visualisation tools specific to the Single Pendulum (2D system). Handles phase portraits, physical animations, and Bayesian update plots.

pygeoinf.data_assimilation.pendulum.single.visualisation.animate_advection(pdf_func: Callable, t_points: ndarray, res: int = 100, x_lim: Tuple[float, float] = (-3.141592653589793, 3.141592653589793), y_lim: Tuple[float, float] = (-2.5, 2.5), title: str = 'Advection', t_start: float = 0.0, L: float = 1.0, m: float = 1.0, g: float = 1.0) → FuncAnimation

Lazy-evaluation animation of PDF advection (Liouville).

pygeoinf.data_assimilation.pendulum.single.visualisation.animate_combined(t_points: ndarray, solution: ndarray, L: float = 1.0, stride: int = 1) → FuncAnimation

Side-by-side animation: Left: Physical Motion (Real space) Right: Phase Space Trajectory (Theta vs P)

pygeoinf.data_assimilation.pendulum.single.visualisation.animate_linear_comparison(t_points: ndarray, sol_nl: ndarray, sol_l: ndarray, L: float = 1.0, theta0_deg: float | None = None) → FuncAnimation

Side-by-side animation comparing the Non-linear (True) and Linear (Approx) physical motion.

pygeoinf.data_assimilation.pendulum.single.visualisation.animate_pendulum(t_points: ndarray, solution: ndarray, L: float = 1.0) → FuncAnimation

Physical space animation (x, y) with a fading trail.

pygeoinf.data_assimilation.pendulum.single.visualisation.animate_phase_portrait(ensemble_trajectories: ndarray, t_points: ndarray) → FuncAnimation

Animates the ensemble of particles moving in phase space (Theta vs P).

pygeoinf.data_assimilation.pendulum.single.visualisation.plot_bayesian_analysis(prior: ProbabilityGrid, likelihood: ProbabilityGrid, posterior: ProbabilityGrid, obs_val: float, obs_time: float) → None

Visualises the Bayesian update step for the single pendulum. Displays Prior, Likelihood, and Posterior side-by-side.

Parameters:

• prior – core.ProbabilityGrid objects.

• likelihood – core.ProbabilityGrid objects.

• posterior – core.ProbabilityGrid objects.

• obs_val – The scalar observation value (theta).

• obs_time – The time at which observation occurred.

pygeoinf.data_assimilation.pendulum.single.visualisation.plot_phase_portrait(ensemble_trajectories: ndarray, t_points: ndarray, title: str | None = None) → None

Plots the ensemble distribution at initial and final times.

pygeoinf.data_assimilation.pendulum.single.visualisation.plot_trajectory_from_initial_condition(y0: ndarray, t_max: float, obs_data: Tuple | None = None, physics_params: dict | None = None, ax: Axes | None = None, color: str = 'k', label: str = 'Trajectory', dt_render: float = 0.02) → Axes

Plots a smooth trajectory starting from y0, optionally overlaying observations.

Module contents

Single Pendulum Submodule.

Exposes physics and visualization tools specifically for the 2D Single Pendulum.

pygeoinf.data_assimilation.pendulum.single.animate_advection(pdf_func: Callable, t_points: ndarray, res: int = 100, x_lim: Tuple[float, float] = (-3.141592653589793, 3.141592653589793), y_lim: Tuple[float, float] = (-2.5, 2.5), title: str = 'Advection', t_start: float = 0.0, L: float = 1.0, m: float = 1.0, g: float = 1.0) → FuncAnimation

Lazy-evaluation animation of PDF advection (Liouville).

pygeoinf.data_assimilation.pendulum.single.animate_combined(t_points: ndarray, solution: ndarray, L: float = 1.0, stride: int = 1) → FuncAnimation

Side-by-side animation: Left: Physical Motion (Real space) Right: Phase Space Trajectory (Theta vs P)

pygeoinf.data_assimilation.pendulum.single.animate_linear_comparison(t_points: ndarray, sol_nl: ndarray, sol_l: ndarray, L: float = 1.0, theta0_deg: float | None = None) → FuncAnimation

Side-by-side animation comparing the Non-linear (True) and Linear (Approx) physical motion.

pygeoinf.data_assimilation.pendulum.single.animate_pendulum(t_points: ndarray, solution: ndarray, L: float = 1.0) → FuncAnimation

Physical space animation (x, y) with a fading trail.

pygeoinf.data_assimilation.pendulum.single.animate_phase_portrait(ensemble_trajectories: ndarray, t_points: ndarray) → FuncAnimation

Animates the ensemble of particles moving in phase space (Theta vs P).

pygeoinf.data_assimilation.pendulum.single.eom(t: float, y: ndarray, L: float = 1.0, m: float = 1.0, g: float = 1.0) → List[float]

Hamilton’s Equations of Motion for a single pendulum.

State vector y = [theta, p_theta]

Parameters:

• t – Time (unused in autonomous system).

• y – State vector [angle, momentum].

• L – Physical parameters.

• m – Physical parameters.

• g – Physical parameters.

Returns:

[d(theta)/dt, d(p_theta)/dt]

Return type:

dydt

pygeoinf.data_assimilation.pendulum.single.eom_linear(t: float, y: ndarray, L: float = 1.0, m: float = 1.0, g: float = 1.0) → ndarray

Linearised EOM around the stable equilibrium (theta=0, p=0).

pygeoinf.data_assimilation.pendulum.single.eom_tangent_linear(t: float, state_aug: ndarray, L: float = 1.0, m: float = 1.0, g: float = 1.0) → ndarray

Coupled ODE for the reference trajectory AND the tangent linear perturbation. Crucial for Extended Kalman Filters (EKF).

State vector (4D): [theta, p, delta_theta, delta_p]

pygeoinf.data_assimilation.pendulum.single.get_coords(theta: float | ndarray, L: float = 1.0) → Tuple[float | ndarray, float | ndarray]

Converts angular state to Cartesian coordinates for visualisation. Standard pendulum convention: 0 is down.

pygeoinf.data_assimilation.pendulum.single.get_jacobian(theta: float, L: float = 1.0, m: float = 1.0, g: float = 1.0) → ndarray

Computes the Jacobian matrix J(theta) of the system at a specific state.

Returns:

2x2 Matrix J

pygeoinf.data_assimilation.pendulum.single.get_linear_propagator(t: float, L: float = 1.0, m: float = 1.0, g: float = 1.0) → ndarray

Returns the analytical propagator matrix P(t) for the linear system. y(t) = P(t) @ y(0)

pygeoinf.data_assimilation.pendulum.single.plot_bayesian_analysis(prior: ProbabilityGrid, likelihood: ProbabilityGrid, posterior: ProbabilityGrid, obs_val: float, obs_time: float) → None

Visualises the Bayesian update step for the single pendulum. Displays Prior, Likelihood, and Posterior side-by-side.

Parameters:

• prior – core.ProbabilityGrid objects.

• likelihood – core.ProbabilityGrid objects.

• posterior – core.ProbabilityGrid objects.

• obs_val – The scalar observation value (theta).

• obs_time – The time at which observation occurred.

pygeoinf.data_assimilation.pendulum.single.plot_phase_portrait(ensemble_trajectories: ndarray, t_points: ndarray, title: str | None = None) → None

Plots the ensemble distribution at initial and final times.

pygeoinf.data_assimilation.pendulum.single.plot_trajectory_from_initial_condition(y0: ndarray, t_max: float, obs_data: Tuple | None = None, physics_params: dict | None = None, ax: Axes | None = None, color: str = 'k', label: str = 'Trajectory', dt_render: float = 0.02) → Axes

Plots a smooth trajectory starting from y0, optionally overlaying observations.