YAML Examples

Asgard examples are defined declaratively in YAML files. Each file specifies an equation, input data, evaluation grid, and output format — everything needed to run a simulation and visualize results, without writing Python code.

Quick Start

# List all available examples
uv run asgard example --list

# Run a single example
uv run asgard example basic/01_integration.yaml

# Run all examples in a category
uv run asgard example -c basic

# Run with the monitor dashboard
uv run asgard example basic/01_integration.yaml --monitor

Example Categories

Examples are organized in the examples/ directory:

Category	Description
`basic/`	Integration, differentiation, fundamental theorem
`advanced/`	Second derivatives, mixed partials, heat equation
`discrete/`	Fibonacci, Markov chains, analytics sequences
`stochastic/`	Brownian motion, Ornstein-Uhlenbeck, Heston model
`optimization/`	Gradient descent, inverse problems
`engineering/`	Real-world SDEs: thermal noise, population dynamics, control

Basic Example

A minimal YAML example for a deterministic 1D solution:

name: Integration Example
description: |
  Integration of a constant function f(x) = 1.
  Expected result: g(x) = x.

equation: "int(f, x) = g"

input:
  coefficients: [1.0, 0.0, 0.0, 0.0]
  dims: [x]

evaluate:
  x:
    range: [0, 3]
    points: 100

expected:
  expression: "x"

output:
  type: Solution1D
  title: "Integration: int(1, x) = x"
  labels:
    x: x
    y: g(x)

Run it:

uv run asgard example basic/01_integration.yaml

Field Reference

Top-Level Fields

Field	Required	Description
`name`	Yes	Display name shown in output and monitor
`description`	No	Multi-line description of what the example demonstrates
`equation`	Yes*	The equation to solve in LEAN syntax
`input`	Yes*	Input data specification
`evaluate`	No	Evaluation grid for deterministic examples
`expected`	No	Analytical solution for comparison
`output`	Yes	Output type and display configuration
`stochastic`	No	Stochastic simulation configuration
`simulate`	No	Time range for stochastic simulations
`initial_condition`	No	Starting value(s) for SDEs
`params`	No	Named parameters substituted into expressions
`coupled`	No	Correlation settings for coupled SDEs
`equations`	No	List of equations for coupled SDE systems

*Either equation + input or equations (for coupled SDEs) is required.

Input Specification

Three ways to provide input data:

Direct coefficients (most common):

input:
  coefficients: [1.0, 2.0, 3.0]   # Taylor coefficients
  dims: [x]                        # Dimension labels

Shape-based fill (for 2D examples):

input:
  shape: [5, 6]
  fill: 1.0
  dims: [x, y]

Generator function (for complex inputs):

input_generator:
  path: examples.discrete.generators:generate_fibonacci
  args:
    n_terms: 20

Evaluate Specification

Defines the grid of points where the solution is evaluated:

evaluate:
  x:
    range: [0, 3]      # Min and max
    points: 100         # Number of points

For 2D examples, specify both dimensions:

evaluate:
  x:
    range: [-1, 1]
    points: 30
  y:
    range: [-1, 1]
    points: 30

Expected Specification

Optional analytical solution for comparison:

expected:
  expression: "x**2 / 2"    # Python expression evaluated at grid points

Output Types

Type	Description	Use Case
`Solution1D`	Line plot of 1D function	Integration, differentiation
`Solution2D`	Heatmap of 2D function	Mixed derivatives, heat equation
`StochasticEnsemble`	Ensemble paths with statistics	SDEs, Monte Carlo
`DiscreteSequence`	Discrete time series plot	Fibonacci, Markov chains
`OptimizationResult`	Optimization progress tracking	Gradient descent

Output configuration:

output:
  type: Solution1D
  title: "My Plot Title"
  labels:
    x: "x axis label"
    y: "y axis label"

Stochastic Examples

Stochastic examples require additional configuration for the SDE simulation.

Single SDE

name: Ornstein-Uhlenbeck Process
description: Mean-reverting process dX = -theta(X - mu)dt + sigma dW

equation: "Y = sde($drift, $sigma, X)"

stochastic:
  calculus: ito          # "ito" (Euler-Maruyama) or "stratonovich" (Heun)
  n_paths: 1000          # Number of Monte Carlo paths
  dt: 0.01               # Time step
  seed: 42               # Random seed for reproducibility

simulate:
  t_start: 0.0
  t_end: 5.0

initial_condition:
  x0: 2.0

params:
  drift: -0.5
  sigma: 0.3

output:
  type: StochasticEnsemble
  title: "Ornstein-Uhlenbeck Process"

Stochastic Fields

Field	Description
`stochastic.calculus`	`"ito"` (default) or `"stratonovich"`
`stochastic.n_paths`	Number of Monte Carlo simulation paths
`stochastic.dt`	Time step for numerical integration
`stochastic.seed`	Random seed (omit for non-reproducible runs)
`simulate.t_start`	Simulation start time
`simulate.t_end`	Simulation end time
`initial_condition.x0`	Initial value of the stochastic process

Coupled SDEs

For systems of multiple stochastic differential equations:

name: Mass-Spring-Damper
description: Position + velocity with stochastic forcing

stochastic:
  calculus: ito
  n_paths: 500
  dt: 0.01
  seed: 42

simulate:
  t_start: 0.0
  t_end: 10.0

coupled:
  correlation: 0.0       # Scalar or matrix of noise correlations

equations:
  - name: X
    description: "Position"
    drift_expr: "x[:, 1]"                              # dx = v dt
    diffusion_expr: "0.0 * ones_like(x[:, 0])"
    x0: 1.0

  - name: V
    description: "Velocity"
    drift_expr: "-k * x[:, 0] - c * x[:, 1]"          # dv = (-kx - cv) dt + sigma dW
    diffusion_expr: "sigma * ones_like(x[:, 1])"
    x0: 0.0

params:
  k: 4.0
  c: 0.5
  sigma: 0.3

output:
  type: StochasticEnsemble
  title: "Mass-Spring-Damper System"

In coupled systems, x[:, i] refers to the i-th state variable across all paths. The params section makes named values available in drift and diffusion expressions.

Analysis Features

Post-simulation analysis can be added to stochastic examples:

analysis:
  percentiles: [5, 25, 50, 75, 95]
  first_passage_time:
    threshold: 1.5

Optimization Pipeline

Optimization examples use a pipeline: block instead of evaluate: to define a parameter- or structure-fitting workflow. The example runner detects the pipeline and delegates to the appropriate optimizer.

Pipeline Fields

Field	Description
`pipeline.dataset`	Training data specification
`pipeline.dataset.generator`	Generate data from a known function
`pipeline.dataset.generator.function`	Target function (e.g., `"y = a * x"`)
`pipeline.dataset.generator.true_params`	Ground-truth parameter values
`pipeline.dataset.generator.x_range`	Input range `[min, max]`
`pipeline.dataset.generator.n_samples`	Number of training samples
`pipeline.initial_circuit`	Starting circuit string (e.g., `"scalar(1.0)"`)
`pipeline.optimizer.method`	Optimizer type (`gradient_descent`)
`pipeline.optimizer.learning_rate`	Step size for gradient updates
`pipeline.optimizer.max_iterations`	Maximum optimization steps
`pipeline.optimizer.tolerance`	Convergence threshold
`pipeline.candidate_circuits`	List of candidate circuits (for structure search)

Example

name: Gradient-Based Optimization
description: |
  Find the parameter 'a' in circuit scalar(a) given data from y = 3*x.

equation: "y = a * x (find a from data)"

pipeline:
  dataset:
    generator:
      function: "y = a * x"
      true_params:
        a: 3.0
      x_range: [1, 5]
      n_samples: 5

  initial_circuit: "scalar(1.0)"

  optimizer:
    method: gradient_descent
    learning_rate: 0.01
    max_iterations: 100
    tolerance: 0.000001

output:
  type: OptimizationResult
  title: "Gradient-Based Parameter Optimization"

Parameter Substitution

Use $ prefix in equations and expressions to reference values from the params section:

equation: "Y = sde($drift, $sigma, X)"
params:
  drift: -0.5
  sigma: 0.3

The loader substitutes $drift and $sigma with their values before compilation.

Writing Your Own Example

Choose a category — pick the examples/ subdirectory that best fits
Follow the naming convention — NN_descriptive_name.yaml (e.g., 05_my_example.yaml)
Start from a template — copy a similar existing example

Test locally:

uv run asgard example path/to/your_example.yaml

View in monitor (optional):

uv run asgard example path/to/your_example.yaml --monitor

Next Steps

Monitor Dashboard — View results interactively
Runtime Concepts — Understand calculi and execution
API Reference — Use the Python API directly