# meep-simulation-workflows

- Author: Tao E. Li
- Repository: TEL-Research-Group/meep
- Version: 20260207225459
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-08
- Source: https://github.com/TEL-Research-Group/meep
- Web: https://mule.run/skillshub/@@TEL-Research-Group/meep~meep-simulation-workflows:20260207225459

---

---
name: meep-simulation-workflows
description: Run/control Meep simulations (Python/Scheme): sim.run step functions, stopping conditions (until/until_after_sources), output patterns, field synchronization, and parallel execution.
---

# meep: Simulation Workflows

## Key Mental Model: `run` Executes Step Functions
- `Simulation.run(*step_funcs, until=...)` timesteps the fields and calls your `step_funcs`.
- Step functions must be callables; do not pass the result of calling a function.
- Use `doc/docs/The_Run_Function_Is_Not_A_Loop.md` whenever a user is confused about "code inside `run`".

## Standard Run Patterns (Python)
Use these patterns as defaults:

```py
# Run for a fixed time while emitting periodic diagnostics.
sim.run(
    mp.at_beginning(mp.output_epsilon),
    mp.at_every(10, lambda sim: print("t =", sim.meep_time())),
    until=200,
)

# Run until sources are off and fields decay (recommended for transients).
sim.run(
    mp.to_appended("ez", mp.at_every(0.5, mp.output_efield_z)),
    until_after_sources=mp.stop_when_fields_decayed(50, mp.Ez, mp.Vector3(), 1e-9),
)
```

## Stopping Conditions You Should Prefer
- `until_after_sources=mp.stop_when_fields_decayed(dt, component, point, decay_by)` for time-domain transients.
- `until_after_sources=mp.stop_when_dft_decayed(tol=..., ...)` when using DFT monitors / near2far.
- If decay is unexpectedly slow, revisit source turn-on/turn-off (`width`, `cutoff`) and PML thickness; high-frequency components near the Nyquist frequency absorb poorly in PML.

## Output Hygiene (Avoid Thousands Of Tiny HDF5 Files)
- Use `mp.to_appended("name", mp.at_every(dt, ...))` to append time slices into a single file.
- Control naming/output directory via `filename_prefix` and `sim.use_output_directory()` (see `doc/docs/Python_User_Interface.md`).

## Accurate Quantities That Mix E And H
- Wrap step functions in `mp.synchronized_magnetic(...)` when outputting/using quantities that combine electric and magnetic fields (e.g. Poynting flux).
- For manual computations:
  - Call `sim.fields.synchronize_magnetic_fields()`
  - Do the computation
  - Call `sim.fields.restore_magnetic_fields()`

## Parallel Execution Quickstart
- MPI PyMeep (Conda `pymeep=*=mpi_mpich_*`): `mpirun -np <N> python <script>.py`
- For scaling/chunking guidance and gotchas: start with `doc/docs/Parallel_Meep.md`.

## Primary documentation references
- `doc/docs/index.md`
- `doc/docs/The_Run_Function_Is_Not_A_Loop.md`
- `doc/docs/Python_User_Interface.md`
- `doc/docs/Python_Developer_Information.md`
- `doc/docs/Parallel_Meep.md`
- `doc/docs/Field_Functions.md`
- `doc/docs/Synchronizing_the_Magnetic_and_Electric_Fields.md`
- `doc/docs/Scheme_Tutorials/Near_to_Far_Field_Spectra.md`
- `doc/docs/Python_Tutorials/Gyrotropic_Media.md`

## Workflow
- Start with the primary references above.
- If details are missing, inspect `references/doc_map.md` for the complete topic document list.
- Use tutorials/examples as executable usage patterns when available.
- Use tests as behavior or regression references when available.
- If ambiguity remains after docs, inspect `references/source_map.md` and start with the ranked source entry points.
- Cite exact documentation file paths in responses.

## Tutorials and examples
- `python/examples`
- `scheme/examples`

## Test references
- `tests`

## Optional deeper inspection
- `python`
- `src`

## Source entry points for unresolved issues
- `src/fields_dump.cpp`
- `src/fields.cpp`
- `src/cw_fields.cpp`
- `python/simulation.py`
- `src/time.cpp`
- `src/step_generic.cpp`
- `src/step_db.cpp`
- `src/step.cpp`
- Prefer targeted source search (for example: `rg -n "<symbol_or_keyword>" python src`).