Basic Usage

python run.py path/to/config.yaml

When you run a simulation:

1. A timestamped folder is created in the same directory as the YAML file
2. The YAML config is copied into this run folder (original remains for easy re-running)
3. All outputs (GIFs, images, data) are saved to the run folder
4. Initial conditions (step 0) are always output along with subsequent steps

Example folder structure after a run:

unit_tests/
└── my_config_YYYY-MM-DD_HH:MM:SS/
    ├── my_config.yaml   # copied config
    └── <monitor outputs>   # GIFs, images, etc.

YAML Configuration Reference

Domain (1D)

1D domains are cell-centered: dx = L/n_points, with grid points at cell centers. This allows CFL = 1 to give exact return after one revolution (no phase drift).

domain:
  x_min: -0.5      # Left boundary
  x_max: 0.5       # Right boundary
  n_points: 100    # Number of grid points (dx = L/n = 0.01)

Domain (2D)

2D domains are cell-centered: dx = Lx/n_points_x, dy = Ly/n_points_y, with grid points at cell centers. This allows CFL = 1 in each direction to give exact return (no phase drift).

domain:
  x_min: -0.5        # Left boundary
  x_max: 0.5         # Right boundary
  n_points_x: 100    # Grid points in x (dx = Lx/n_points_x)
  y_min: -0.5        # Bottom boundary
  y_max: 0.5         # Top boundary
  n_points_y: 100    # Grid points in y (dy = Ly/n_points_y)

Time

time:
  dt: 0.01         # Time step size
  n_steps: 200     # Number of steps

Velocity

velocity: [0.5]        # 1D: advection velocity (list with 1 element)
velocity: [0.5, 0.0]   # 2D: (u, v) advection velocity

Fields

fields:
  - name: alpha
    initial_condition: "0.5 * (tanh((0.1 + x) / 0.02) + tanh((0.1 - x) / 0.02))"
    boundary:
      type: periodic   # or neumann, dirichlet
    sharpening: true   # optional per-field override

Per-field sharpening: Each field can override the global sharpening setting by adding sharpening: true or sharpening: false. This allows comparing sharpened vs non-sharpened fields in the same simulation.

Initial conditions are Python expressions evaluated with:

• 1D: x (grid coordinates)
• 2D: x, y (meshgrid), r = sqrt(x² + y²) (radial distance)
• Math functions: sin, cos, tanh, exp, sqrt, pi, np (numpy)

Boundary Condition Types

Type	Parameters
periodic	(none)
neumann	gradient_left, gradient_right
dirichlet	value_left, value_right

Solver

solver:
  type: upwind    # First-order upwind advection

Timestepper

timestepper:
  type: euler     # or rk4

Sharpening (Optional)

sharpening:
  enabled: true
  method: cl       # cl (Chiu-Lin) or pm (Parameswaran-Mandal)
  eps_target: 0.01 # Target interface thickness
  strength: 1.0    # Sharpening strength (Gamma)

Output Monitors

When you use run.py, output is written to the timestamped run folder (the output.directory in the YAML is overridden). You can omit output.directory from your YAML.

output:
  monitors:
    - type: console      # Progress bar (no file output)
    - type: gif
      every_n_steps: 20
      field: alpha
    - type: png
      every_n_steps: 50
      field: alpha
    - type: txt
      every_n_steps: 10
      field: alpha
    - type: curve
      every_n_steps: 10
      field: alpha
    - type: hdf5
      every_n_steps: 10
      fields: [alpha]
    # 2D-only monitors:
    - type: contour_gif
      every_n_steps: 20
      field: alpha
      contour_level: 0.5      # default 0.5
      show_centroid: true     # optional
      show_crosshairs: true   # optional
    - type: contour_compare_gif
      every_n_steps: 20
      compare_fields:
        - field: alpha_no_sharp
          contour_levels: [0.5]
          color: blue
          linestyle: "-"
        - field: alpha_pm
          contour_levels: [0.25, 0.5, 0.75]
          color: red
          linestyle: "--"

Monitor Types

Type	Output	Parameters
console	Progress bar (tqdm)	every_n_steps
png	PNG images	field, every_n_steps or at_times
pdf	PDF images	field, every_n_steps or at_times
gif	Animated GIF	field, every_n_steps or at_times
hdf5	HDF5 file	fields (list), every_n_steps or at_times
txt	Columnar text	field, every_n_steps or at_times
curve	Curve format (x, y)	field, every_n_steps or at_times
contour_gif	Animated contour GIF (2D)	field, contour_level, show_centroid, show_crosshairs
contour_compare_gif	Compare multiple fields' contours (2D)	compare_fields (list of field configs with contour_levels, color, linestyle)
compare_gif	Compare multiple 1D fields on one plot	compare_fields (list with field, color, linestyle)