TIDAL Documentation#

TIDAL (Tensor Integration and Derivation for Any Lagrangian) is a symbolic physics pipeline that derives PDEs from Lagrangians using xAct/Mathematica and simulates them numerically with py-pde. All equation structure comes from symbolic computation — no physics is hardcoded.

Key Features#

  • Symbolic Pipeline: Lagrangian → Euler-Lagrange → Component Decomposition → JSON → PDE Simulation

  • CLI Tool: tidal command with derive, simulate, measure, inspect, list, and validate subcommands

  • 20 Working Examples: Spanning 1+1D through 3+1D spacetimes

  • Multi-Field Support: Scalars, vectors, and rank-3+ tensors with cross-field coupling

  • Curvilinear Coordinates: Automatic Christoffel symbol computation for non-Cartesian grids

  • Parameter Sweeps: Override symbolic coefficients at runtime without re-deriving

  • 900+ Python Tests + ~115 Wolfram Tests: Comprehensive validation of both pipeline stages

Quick Start#

Install and run:

# Install
uv sync --all-extras

# List available equation specifications
tidal list

# Simulate a Klein-Gordon field
tidal simulate examples/data/klein_gordon_1d.json --t-end 20 --ic gaussian

# Derive equations from a Lagrangian (requires wolframscript)
tidal derive examples/scalar_field/theory.toml --run

# Inspect an equation system
tidal inspect examples/data/chern_simons.json

# Run a pipeline example
cd examples/scalar_field && bash run.sh

API Reference

Indices and Tables#