Several major v16 features will be advertised in the README and HISTORY.md but lack dedicated tutorial content in the documentation. This issue tracks the tutorials that should be added.
1. @brownians and @poissonians DSL options
Current state: Mentioned in the index.md example and listed in the API page (core_api.md lines 95-96), but no dedicated tutorial section exists. The coupled_non_crn_models.md page mentions them only in a one-line summary. The noise_modelling_approaches.md example page does not mention them at all.
What to add:
- A section in
coupled_non_crn_models.md (or dsl_advanced.md) demonstrating:
- How to declare brownians/poissonians via the DSL (
@brownians, @poissonians)
- How to use them in
@equations blocks to add environmental noise to non-species variables
- How brownians interact with SDE problem creation (auto-enables
mtkcompile)
- How poissonians interact with jump problem creation
- A worked example showing an ODE for a non-species variable with additive Brownian noise (similar to the README cell-volume example but with more explanation)
- A mention/cross-reference in
noise_modelling_approaches.md as a fourth approach for modeling noise
2. HybridProblem, hybrid_model, and PhysicalScale metadata
Current state: hybrid_model now has an API @docs block in core_api.md but there is zero tutorial content. PhysicalScale enum and per-reaction scale metadata are completely undocumented in tutorials.
What to add:
- A new section in
simulation_introduction.md (or a new dedicated page) covering:
- The concept of hybrid models mixing ODE, SDE, and Jump reactions
- How to set
PhysicalScale metadata on individual reactions (via DSL and programmatic API)
- The
PhysicalScale enum values: Auto, ODE, SDE, Jump, VariableRateJump
- Creating a
HybridProblem from a ReactionSystem with mixed-scale reactions
- Using
hybrid_model to get the intermediate System
- A worked example: e.g., a system where some reactions are deterministic (ODE) while others are stochastic (Jump)
- Clarify the relationship:
JumpProblem now produces pure-jump systems only; for mixed ODE+Jump or SDE+Jump, use HybridProblem
3. Unit validation
Current state: API @docs blocks exist in core_api.md for validate_units, assert_valid_units, unit_validation_report, etc. The @unit_checks DSL option is listed. But there is no tutorial showing how to use any of this.
What to add:
- A new page (e.g.,
model_creation/unit_validation.md) or a section in an existing page covering:
- Enabling unit checks via
@unit_checks true in the DSL
- Attaching units to species and parameters (via DynamicQuantities.jl symbolic units
us"...")
- How Catalyst validates dimensional consistency of reactions (rates vs. stoichiometry)
- Using
validate_units(rs) and assert_valid_units(rs) post-hoc
- Reading a
unit_validation_report
- A worked example showing a model with correct units and one with intentional unit errors
- Note about using symbolic units (
us"...") vs. concrete units (u"...")
4. @discretes and @tstops DSL options
Current state: Listed in core_api.md (lines 97, and @tstops not listed at all). @discretes appears in one code example in events.md (line 177) without much explanation. @tstops is not mentioned anywhere in the docs.
What to add:
- A section in
events.md or dsl_advanced.md covering:
- What discrete parameters are and when to use them (time-dependent parameters modified by events)
- How to declare them via
@discretes in the DSL
- A worked example showing discrete parameters used with event callbacks
- For
@tstops:
- What solver time stops are
- How to declare them via
@tstops in the DSL
- When they are needed (e.g., ensuring the solver hits specific time points for discrete events)
5. mtkcompile keyword documentation
Current state: Mentioned in the Hodgkin-Huxley example and the FAQs, but not explained in the primary tutorials where users would encounter it.
What to add:
- A note/subsection in
coupled_non_crn_models.md and/or simulation_introduction.md explaining:
- When
mtkcompile = true is needed (algebraic equations require it; brownians auto-enable it)
- What it does (runs ModelingToolkitBase's
mtkcompile to structurally simplify the system)
- The error message users will see if they forget it with algebraic equations
- That it is automatically enabled when brownians are present (so users don't need to pass it in that case)
Several major v16 features will be advertised in the README and HISTORY.md but lack dedicated tutorial content in the documentation. This issue tracks the tutorials that should be added.
1.
@browniansand@poissoniansDSL optionsCurrent state: Mentioned in the index.md example and listed in the API page (core_api.md lines 95-96), but no dedicated tutorial section exists. The coupled_non_crn_models.md page mentions them only in a one-line summary. The noise_modelling_approaches.md example page does not mention them at all.
What to add:
coupled_non_crn_models.md(ordsl_advanced.md) demonstrating:@brownians,@poissonians)@equationsblocks to add environmental noise to non-species variablesmtkcompile)noise_modelling_approaches.mdas a fourth approach for modeling noise2.
HybridProblem,hybrid_model, andPhysicalScalemetadataCurrent state:
hybrid_modelnow has an API@docsblock in core_api.md but there is zero tutorial content.PhysicalScaleenum and per-reaction scale metadata are completely undocumented in tutorials.What to add:
simulation_introduction.md(or a new dedicated page) covering:PhysicalScalemetadata on individual reactions (via DSL and programmatic API)PhysicalScaleenum values:Auto,ODE,SDE,Jump,VariableRateJumpHybridProblemfrom aReactionSystemwith mixed-scale reactionshybrid_modelto get the intermediateSystemJumpProblemnow produces pure-jump systems only; for mixed ODE+Jump or SDE+Jump, useHybridProblem3. Unit validation
Current state: API
@docsblocks exist in core_api.md forvalidate_units,assert_valid_units,unit_validation_report, etc. The@unit_checksDSL option is listed. But there is no tutorial showing how to use any of this.What to add:
model_creation/unit_validation.md) or a section in an existing page covering:@unit_checks truein the DSLus"...")validate_units(rs)andassert_valid_units(rs)post-hocunit_validation_reportus"...") vs. concrete units (u"...")4.
@discretesand@tstopsDSL optionsCurrent state: Listed in core_api.md (lines 97, and
@tstopsnot listed at all).@discretesappears in one code example in events.md (line 177) without much explanation.@tstopsis not mentioned anywhere in the docs.What to add:
events.mdordsl_advanced.mdcovering:@discretesin the DSL@tstops:@tstopsin the DSL5.
mtkcompilekeyword documentationCurrent state: Mentioned in the Hodgkin-Huxley example and the FAQs, but not explained in the primary tutorials where users would encounter it.
What to add:
coupled_non_crn_models.mdand/orsimulation_introduction.mdexplaining:mtkcompile = trueis needed (algebraic equations require it; brownians auto-enable it)mtkcompileto structurally simplify the system)