YAML Examples Monitor Dashboard Storage Troubleshooting

Troubleshooting Guide

This guide covers common issues and their solutions when working with Gimle.

Parse Errors

Invalid Equation Syntax

Error:

ParseError: Unexpected token 'd' at position 0

Cause: Using non-LEAN syntax (e.g., d/dx instead of diff).

Solution: Use LEAN-style syntax:

# Wrong
eq = GimleEquation.from_string("d/dx f")

# Correct
eq = GimleEquation.from_string("diff(f, x)")

Missing Parentheses

Error:

ParseError: Expected '(' at position 4

Cause: Function calls require parentheses.

Solution:

# Wrong
eq = GimleEquation.from_string("int f, x")

# Correct
eq = GimleEquation.from_string("int(f, x)")

Unbalanced Parentheses

Error:

ParseError: Unexpected end of input

Cause: Mismatched parentheses in expression.

Solution: Count parentheses carefully:

# Wrong
eq = GimleEquation.from_string("int(diff(f, x), y")

# Correct
eq = GimleEquation.from_string("int(diff(f, x), y)")

Compilation Errors

Cannot Compile Equation

Error:

CompilationError: Cannot compile equation to circuit

Cause: The equation contains operations that don't have circuit equivalents.

Solution: Ensure equation uses supported operations:

Degree Mismatch

Error:

ValidationError: Composition degree mismatch: output 2 != input 1

Cause: Trying to compose circuits with incompatible degrees.

Solution: Check circuit degrees before composition:

c1 = GimleCircuit.from_string("add")      # in=2, out=1
c2 = GimleCircuit.from_string("split")    # in=1, out=2

print(f"c1: {c1.input_degree} -> {c1.output_degree}")
print(f"c2: {c2.input_degree} -> {c2.output_degree}")

# c1.compose(c2) requires c1.output_degree == c2.input_degree

Execution Errors

Input Count Mismatch

Error:

InputValidationError: Circuit expects 2 inputs, got 1

Cause: Number of input arrays doesn't match circuit input degree.

Solution: Provide correct number of inputs:

circuit = GimleCircuit.from_string("add")  # input_degree = 2

# Wrong
result = sim.simulate(circuit, [data1], dim_labels=("x",))

# Correct
result = sim.simulate(circuit, [data1, data2], dim_labels=("x",))

Shape Mismatch

Error:

ValueError: All input arrays must have same shape

Cause: Input arrays have different shapes.

Solution: Ensure all inputs have identical shapes:

import jax.numpy as jnp

data1 = jnp.array([[1.0, 2.0, 3.0]])
data2 = jnp.array([[4.0, 5.0, 6.0]])  # Same shape as data1

result = sim.simulate(circuit, [data1, data2], dim_labels=("x",))

Dimension Label Mismatch

Error:

ValueError: dim_labels has 2 dimensions but data has 1

Cause: Number of dimension labels doesn't match data dimensions.

Solution: Match dim_labels to data shape:

# 1D data
data = jnp.array([[1.0, 2.0, 3.0]])  # Shape: (1, 3)
result = sim.simulate(circuit, [data], dim_labels=("x",))

# 2D data
data = jnp.array([[[1.0, 2.0], [3.0, 4.0]]])  # Shape: (1, 2, 2)
result = sim.simulate(circuit, [data], dim_labels=("x", "y"))

Rewrite Errors

Unknown Rule Group

Error:

RewriteError: Unknown rule group 'my_rules'

Cause: Specified rule group doesn't exist.

Solution: Use valid rule group names:

# Available equation rule groups
eq.rewrite("eq_integration_rules")
eq.rewrite("eq_elimination_rules")
eq.rewrite("eq_ring_rules")
eq.rewrite("eq_full")

# For compilation
eq.rewrite("equation_to_circuit")

Rewrite Doesn't Apply

Issue: Rewrite returns unchanged equation.

Cause: No rules match the current equation structure.

Solution: Check if equation is already simplified or use different rule group:

eq = GimleEquation.from_string("f")

# Already in simplest form - no rewrite happens
new_eq, rules = eq.rewrite("eq_elimination_rules")
print(rules)  # [] - no rules applied

Storage Issues

File Not Found

Error:

FileNotFoundError: No such file or directory: './results/solutions/sim_001.json'

Cause: Trying to load non-existent result.

Solution: Check if file exists or list available results:

storage = AsgardStorage("./results")

# List what's available
available = storage.list_runs()
print(available)

# Then load a run by its ID
run = storage.load_run("run-uuid-here")

S3 Permission Denied

Error:

botocore.exceptions.ClientError: Access Denied

Cause: AWS credentials don't have required permissions.

Solution: Check IAM permissions:

Stochastic Simulation Issues

Missing Required Parameters

Error:

InputValidationError: t_range required for stochastic simulation

Cause: Stochastic simulation requires additional parameters.

Solution: Provide all required parameters:

from gimle.asgard.runtime.stream_evaluator import StochasticCalculus

calculus = StochasticCalculus(
    drift=0.0,
    diffusion=1.0,
    n_paths=1000,
    dt=0.01
)

result = sim.simulate(
    circuit,
    [input_data],
    dim_labels=("t",),
    calculus=calculus,
    t_range=(0, 10),      # Required
    x0=1.0,               # Required
    drift_fn=lambda x, t: -x,        # Required
    diffusion_fn=lambda x, t: 0.5,   # Required
)

Evaluating Stochastic Results

Error:

ValueError: Cannot evaluate stochastic results at arbitrary points

Cause: Trying to call .evaluate() on stochastic results.

Solution: Use pre-computed trajectories:

# For stochastic results, use trajectories directly
paths = result.trajectories       # Shape: (n_paths, n_steps)
stats = result.get_statistics()   # Mean, std, quantiles

# Or get a single path
traj = result.get_trajectory(path_idx=0)

Performance Issues

Slow Compilation

Issue: Circuit compilation takes a long time.

Cause: Large or deeply nested circuits.

Solution:

  1. Simplify circuits before compilation
  2. Use simpler equation structures
  3. Consider breaking into smaller circuits

Memory Issues

Issue: Out of memory during simulation.

Cause: Large data arrays or too many Monte Carlo paths.

Solution:

  1. Reduce n_paths for stochastic simulations
  2. Use smaller spatial grids
  3. Process data in chunks

Getting Help

If you encounter issues not covered here:

  1. Check the API Reference
  2. Search existing GitHub Issues
  3. Create a new issue with:
    • Error message
    • Minimal reproducible example
    • Python and Gimle versions