Refine assignment subtitles for clarity across multiple modules

Author: Daniel Precioso, PhD

modules/agent-based-modeling/assignment.qmd

@@ -1,6 +1,6 @@
 ---
 title: "Assignment"
-subtitle: "Session 8: Agent-Based Traffic"
+subtitle: "Agent-Based Traffic"
 format: html
 ---
 

modules/cellular-automata/assignment.qmd

@@ -1,6 +1,6 @@
 ---
 title: "Assignment"
-subtitle: "Session 7: Cellular Automata"
+subtitle: "Cellular Automata"
 format: html
 ---
 

modules/ode-1d/assignment.qmd

@@ -1,29 +1,67 @@
 ---
 title: "Assignment"
-subtitle: "ODEs in 1D: Spruce Budworm model"
+subtitle: "Spruce Budworm App"
 format: html
 ---
 
-Implement the complete Streamlit application for the **Spruce Budworm model** as described [here](spruce-budworm.qmd), following the sections from [Implementing the ODE Function](spruce-budworm.qmd#sec-implementing-ode-function) through [Building the Streamlit Application](spruce-budworm.qmd#sec-streamlit-application) [@strogatz2024nonlinear]. Ensure that all functions are correctly defined and integrated into the app. Test the application thoroughly to confirm that it behaves as expected.
+This assignment turns the Session 1 workflow into a complete mini-project. The spruce budworm model combines a scalar ODE, equilibrium structure, numerical integration, and an interactive front end [@strogatz2024nonlinear].
 
-Answer at least three of the exploration questions from [Exploration Questions](spruce-budworm.qmd#sec-exploration-questions) and document your findings in a brief report (1-2 pages). You are encouraged to use LaTeX here. Include graphs demonstrating different behaviors observed during your exploration.
+You can follow the guide here:
 
-If you want to go the extra mile, here are some additional challenges you can tackle:
+[Spruce Budworm Model](spruce-budworm.qmd){.btn .btn-primary}
 
-- Create a GitHub repository for your project and push your code there. You can include the text of your report in the repository as well.
-- Deploy your Streamlit app using Streamlit Cloud or another hosting service. Share the link in your report.
-- Implement some of the advanced features mentioned in [Building the Streamlit Application](spruce-budworm.qmd#sec-streamlit-application).
-- Instead of using SciPy's built-in ODE solver, implement your own simple Euler or Runge-Kutta integrator and compare results.
+## Summary of Goals
+
+Your submission should show that you can do three things:
+
+1. Implement the spruce budworm model and its supporting visualizations.
+2. Build an interactive app that evolves the dynamics correctly.
+3. Interpret the resulting equilibria, bistability, and hysteresis behavior.
+
+::: {.callout-note}
+## Submission
+
+Submit two files:
+
+1. The Python code for your Streamlit app and any helper module you created.
+2. A short report, 1 to 2 pages, that answers the exploration questions you chose.
+:::
+
+## Required
+
+1. Implement the `spruce_budworm()` right-hand side and the plotting helpers described in [spruce-budworm.qmd](spruce-budworm.qmd).
+2. Build a Streamlit app that includes the phase portrait, the time-series plot, and an “Evolve Forward” control.
+3. Use `st.session_state` so the simulation persists across interactions.
+4. Answer at least three exploration questions from [Exploration Questions](spruce-budworm.qmd#sec-exploration-questions).
+5. Include figures that support your interpretation.
+
+## Short Discussion
+
+Your report should address questions such as:
+
+1. How many equilibria appear for the parameter values you explored?
+2. Did different initial conditions converge to different long-run states?
+3. Did you observe signs of hysteresis or threshold behavior?
+
+## Optional Extensions
+
+- Create a GitHub repository for your project and include the report.
+- Deploy the Streamlit app and share the link.
+- Add a reset button or multiple trajectories.
+- Implement Euler or Runge–Kutta yourself and compare with SciPy.
 
 ## Tips for Success
 
-- **Start simple:** Get [Implementing the ODE Function](spruce-budworm.qmd#sec-implementing-ode-function) working first, then build up.
-- **Test incrementally:** Verify each function works before moving to the next.
-- **Use the reference:** The provided code (and additional documentation) is there to help you understand the structure.
-- **Experiment:** Try different parameter values and see what happens.
-- **Collaborate:** Discuss with your teammates, divide the work if needed. You can also work separately and then compare your implementations.
-- **Ask questions:** If you're stuck, ask for help!
+- Start with the ODE and the static plots before you build the app.
+- Test each helper function separately.
+- Keep the simulation state logic simple before adding extra features.
+- Use the reference script to compare shapes and parameter behavior.
+- Focus on interpretation, not only on getting the app to run.
+
+::: {.callout-tip}
+Reference code is available in [amlab/odes_1d/spruce_budworm.py](../../amlab/odes_1d/spruce_budworm.py).
+:::
 
 \vspace{1cm}
 
-**Good luck and enjoy your coding!**
+Good luck.

modules/ode-1d/index.qmd

@@ -1,101 +1,94 @@
 ---
 title: "Ordinary Differential Equations in 1D"
-subtitle: "Numerical Integration with SciPy"
+subtitle: "Initial Value Problems and Nonlinear Rate Laws"
 format: html
 ---
 
-Numerical integration is fundamental for solving ordinary differential equations (ODEs) that don't have analytical solutions [@strogatz2024nonlinear; @virtanen2020scipy]. In this first session, you will learn how to:
+This first session builds the numerical workflow used throughout the whole course: define a right-hand side, choose an initial condition, integrate forward in time, and interpret the solution [@strogatz2024nonlinear; @virtanen2020scipy].
 
-- Formulate ODEs in Python.
-- Use SciPy's `solve_ivp` to numerically integrate ODEs.
-- Visualize solutions and explore parameter spaces.
-- Apply these techniques to real-world models.
+## From One Variable to Small Systems
 
+The core mathematical object is the initial value problem
 
-## Contents
+$$
+\dot y = f(t, y),
+\qquad
+y(t_0) = y_0.
+$$ {#eq-ode-1d-index-1}
 
-- [SIR Epidemic Model](sir.qmd)
-- [Michaelis–Menten Enzyme Kinetics](michaelis-menten.qmd)
-- [Spruce Budworm Population Model](spruce-budworm.qmd)
-- [Assignment](assignment.qmd)
+In a scalar problem, $y(t)$ is one number. In a small system, $y(t)$ becomes a vector. The numerical workflow stays the same.
 
-## The Initial Value Problem
+That is why this session starts with the label “1D” but already includes the SIR model: the main skill is not the number of components, but how you turn a rate law into a computable trajectory.
 
-An **initial value problem (IVP)** consists of:
+## Case Studies
 
-$$\frac{dy}{dt} = f(t, y), \quad y(t_0) = y_0$$ {#eq-ode-1d-index-1}
+Start with a classical epidemic model and see how a coupled ODE system fits into the same `solve_ivp` pipeline.
 
-Where:
-- $f(t, y)$ is the rate of change function
-- $y_0$ is the initial condition at time $t_0$
+[SIR Epidemic Model](sir.qmd){.btn .btn-primary}
 
-## SciPy's `solve_ivp`
+Then study a saturating nonlinear rate law through a Michaelis–Menten inspired example.
 
-The `scipy.integrate.solve_ivp` function is the standard tool for solving ODEs in Python. Try the following code:
+[Michaelis–Menten Kinetics](michaelis-menten.qmd){.btn .btn-primary}
 
-```python
-import numpy as np
-from scipy.integrate import solve_ivp
+Finally, combine phase-line reasoning, numerical integration, and interactivity in the spruce budworm model.
 
-def exponential_decay(t, y):
-     return -0.5 * y
+[Spruce Budworm Model](spruce-budworm.qmd){.btn .btn-primary}
 
-t_span = [0, 10]
-y0 = [2, 4, 8]
-sol = solve_ivp(
-    fun=exponential_decay,
-    t_span=t_span, 
-    y0=y0)
+When the workflow is clear, move to the assignment.
 
-print(sol.t)
+[Assignment](assignment.qmd){.btn .btn-secondary}
 
-print(sol.y)
-```
+## Learning Goals
 
-**How does `solve_ivp` work?** Let's understand its parameters (copied from the [documentation](https://docs.scipy.org/doc/scipy/reference/generated/scipy.integrate.solve_ivp.html)):
+- Formulate an ODE or a small ODE system in Python.
+- Use `scipy.integrate.solve_ivp()` to integrate an initial value problem.
+- Interpret trajectories in time and connect them to parameters.
+- Recognize threshold, saturation, and bistability effects in simple models.
+- Reuse the same solver workflow across very different applications.
 
-- `fun`: Right-hand side of the system: the time derivative of the state $y$ at time $t$. The calling signature is `fun(t, y)`, where `t` is a scalar and `y` is an ndarray with `len(y) = len(y0)`. Additional arguments need to be passed if `args` is used (see documentation of `args` argument). `fun` must return an array of the same shape as `y`.
-   In our example, `exponential_decay` defines the ODE $\frac{dy}{dt} = -0.5y$, which models exponential decay $y(t) = y_0 e^{-0.5t}$.
-- `t_span`: Interval of integration $(t_0, t_f)$. The solver starts with $t=t_0$ and integrates until it reaches $t=t_f$. Both $t_0$ and $t_f$ must be floats or values interpretable by the float conversion function.
-- `y0`: Initial state. For problems in the complex domain, pass `y0` with a complex data type (even if the initial value is purely real).
+## Flow of This Session
 
-You can also specify additional parameters:
-- `method`: Integration method to use. Common choices include `'RK45'` (default), `'RK23'`, `'DOP853'`, `'Radau'`, `'BDF'`, and `'LSODA'`.
-- `t_eval`: Times at which to store the computed solution, must be sorted and lie within `t_span`. If None (default), use points selected by the solver.
-- `args`: Additional arguments to pass to the user-defined functions. If, for example, `fun` has the signature `fun(t, y, a, b, c)`, then `args=(a, b, c)`.
+- Write the right-hand side of the model.
+- Choose parameters, a time span, and an initial condition.
+- Integrate with `solve_ivp()`.
+- Plot the solution and interpret the result.
+- Compare how the behavior changes when you vary parameters or initial data.
 
-## Systems of ODEs
+## What do we need?
 
-For multiple coupled equations, return a list or array of derivatives:
+### `scipy.integrate.solve_ivp`
+
+This is the main solver for initial value problems in the course. It takes the right-hand side `fun(t, y)`, the interval `t_span`, the initial state `y0`, and optional arguments such as `t_eval`, `method`, and `args`.
 
 ```python
-def sir_model(t, y, beta, gamma):
-    S, I, R = y
-    N = S + I + R
-    
-    dSdt = -beta * S * I / N
-    dIdt = beta * S * I / N - gamma * I
-    dRdt = gamma * I
-    
-    return [dSdt, dIdt, dRdt]
+import numpy as np
+from scipy.integrate import solve_ivp
+
+
+def exponential_decay(t, y):
+    return -0.5 * y
+
+
+sol = solve_ivp(
+    exponential_decay,
+    t_span=(0, 10),
+    y0=[2.0],
+    t_eval=np.linspace(0, 10, 200),
+)
 ```
 
-## Best Practices
+### `numpy`
+
+Use NumPy arrays for initial conditions, evaluation grids, and post-processing of trajectories.
 
-1. **Always check convergence**: Plot solutions at different tolerances
-2. **Use appropriate methods**: `'RK45'` (default) works well for most problems
-3. **Vectorize when possible**: Makes code faster and cleaner
-4. **Document parameters**: Keep track of units and meanings
-5. **Validate against known solutions**: Test your implementation
+### `matplotlib.pyplot`
 
-## Next Steps
+Use Matplotlib to visualize time series, parameter comparisons, and phase-line style diagnostics.
 
-Apply these techniques to the classical models in Session 1:
-- SIR epidemiological model
-- Spruce budworm population dynamics
-- Michaelis–Menten enzyme kinetics
+### Why start with `solve_ivp()`?
 
-## Resources
+Because once you understand the initial value problem pipeline, you can reuse it almost unchanged in later sessions on planar systems, coupled oscillators, and PDE-inspired reductions.
 
-- [SciPy solve_ivp documentation](https://docs.scipy.org/doc/scipy/reference/generated/scipy.integrate.solve_ivp.html)
-- [Python for ODEs tutorial](https://python-numerical-methods.berkeley.edu/notebooks/chapter22.00-ODE-Initial-Value-Problems.html)
+::: {.callout-tip}
+The default `RK45` method is a good first choice for most examples in this session. Later sessions will make the method choice itself part of the modeling discussion.
+:::

modules/ode-1d/michaelis-menten.qmd

@@ -1,18 +1,44 @@
 ---
 title: "Michaelis–Menten Enzyme Kinetics"
-subtitle: "1D Ordinary Differential Equations"
+subtitle: "Saturation as a One-Dimensional Rate Law"
 format: html
 ---
 
-Michaelis–Menten kinetics is a foundational model in biochemical reaction dynamics [@michaelis1913kinetik]. It relates substrate concentration to reaction rate using a saturating nonlinearity.
+Michaelis–Menten kinetics is one of the standard examples of a saturating nonlinear rate law [@michaelis1913kinetik]. The classical instantaneous rate is
 
-The (simplified) substrate dynamics implemented in the reference script is:
+$$
+v(s) = \frac{V_{\max} s}{K_m + s},
+$$
+
+where $V_{\max}$ is the maximum rate and $K_m$ is the Michaelis constant.
+
+In the reference script used in this course, the same saturating expression is reused as a simple teaching ODE,
 
 $$
 \dot s = \frac{V_{\max}s}{K_m + s}
 $$ {#eq-ode-1d-michaelis-menten-1}
 
-where $V_{\max}$ is the maximum rate and $K_m$ is the Michaelis constant.
+This is not a full enzyme-substrate mass-action model. It is a compact one-dimensional example that lets you study how saturation changes both the rate curve and the time evolution of the state variable.
+
+## Small and Large Concentration Regimes
+
+The rate law has two useful asymptotic regimes:
+
+$$
+v(s) \approx \frac{V_{\max}}{K_m} s \quad \text{for } s \ll K_m,
+\qquad
+v(s) \approx V_{\max} \quad \text{for } s \gg K_m.
+$$
+
+So the system is approximately linear at small $s$ and nearly constant-rate at large $s$.
+
+## Implement the Saturating Rate Law
+
+```python
+def michaelis_menten(t, s, vmax=1.0, km=0.5):
+	dsdt = (vmax * s) / (km + s)
+	return dsdt
+```
 
 ## Reference Implementation {#sec-reference}
 
@@ -42,6 +68,12 @@ plt.show()
 plt.close()
 ```
 
+## Interpret the Parameters
+
+- Increasing $V_{\max}$ raises the saturation plateau.
+- Increasing $K_m$ shifts the curve so larger values of $s$ are needed before the rate is close to saturation.
+- In the teaching ODE used here, larger $V_{\max}$ also makes the state variable evolve faster in time.
+
 ## Exploration {#sec-exploration}
 
 1. Increase $V_{\max}$ and observe how the rate curve changes.
@@ -52,3 +84,10 @@ plt.close()
 ```bash
 python amlab/odes_1d/michaelis_menten.py
 ```
+
+## What's Next?
+
+The Michaelis–Menten example highlights saturation. The spruce budworm model adds phase-line reasoning, multiple equilibria, and bistability.
+
+[Spruce Budworm Model](spruce-budworm.qmd){.btn .btn-primary}
+[Back to Session Index](index.qmd){.btn .btn-secondary}