Merge remote-tracking branch 'origin/master' into claude/gallant-yonath-faecaa

Author: mrp089

.github/workflows/gui.yml

@@ -32,7 +32,7 @@ jobs:
 
       - name: Install Flask dependencies
         # The GUI only needs Flask, not the compiled pysvzerod extension.
-        run: uv sync --no-install-project --group gui
+        run: uv sync --no-install-project --no-default-groups --group gui
 
       - name: Start Flask Application
         run: |

.github/workflows/test.yml

@@ -28,7 +28,7 @@ jobs:
 
       - name: Build and test
         run: |
-          uv sync
+          uv sync --no-default-groups --group dev
           cd tests
           uv run pytest -v --durations=0 --ignore=test_dirgraph.py
 
@@ -98,11 +98,10 @@ jobs:
             -DENABLE_DISTRIBUTION=ON
           uv run --no-sync cmake --build $build --parallel 2
 
-          # build installer
-          choco install nsis -y
-          echo "C:\Program Files (x86)\NSIS\Bin" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
+          # Build a portable package on CI. This avoids the flaky Chocolatey
+          # NSIS install path while still producing a Windows artifact.
           cd $build
-          cpack -C Release
+          cpack -G ZIP -C Release
           Copy-Item distribution\svZeroDSolver_* -Destination ..\
 
       - name: Upload installer

.github/workflows/test_visualization.yml

@@ -22,7 +22,7 @@ jobs:
       - name: Install dependencies
         # The dirgraph test only needs the Python dev tooling, not the compiled
         # pysvzerod extension, so skip building the project.
-        run: uv sync --no-install-project
+        run: uv sync --no-install-project --no-default-groups --group dev
 
       - name: Install Graphviz
         if: runner.os == 'Linux'

.gitignore

@@ -39,6 +39,9 @@ build*/
 # Node modules (for directed graph visualization)
 node_modules/
 
+# Allow csv for target files in svZeroDTuner examples
+!applications/svZeroDTuner/examples/**/targets/**/*.csv
+
 # Virtual environments
 venv/
 .venv/

README.md

@@ -15,6 +15,7 @@ You can find more information under the following links:
 
 * [**Documentation**](https://simvascular.github.io/svZeroDSolver)
 * [**Developer Guide**](https://simvascular.github.io/svZeroDSolver/developer_guide.html)
+* [**svZeroDTuner Guide**](https://simvascular.github.io/svZeroDSolver/tuner.html)
 * [**Bug Reports**](https://github.com/simvascular/svZeroDSolver/issues)
 * [**Forum**](https://github.com/simvascular/svZeroDSolver/discussions)
 * [**About SimVascular**](https://simvascular.github.io)

applications/svZeroDTuner/.gitignore

@@ -0,0 +1,6 @@
+baseline_results/
+optimization_results*/
+sensitivity_results/
+reference_codes/
+
+

applications/svZeroDTuner/examples/closed_loop_Regazzoni/README.md

@@ -0,0 +1,106 @@
+# closed_loop_Regazzoni example
+
+For full svZeroDTuner usage and configuration guidance, see the svZeroDTuner guide on the docs site: <https://simvascular.github.io/svZeroDSolver/tuner.html>.
+
+This example tunes a four-chamber closed-loop heart model (based on Regazzoni et al.) with
+systemic and pulmonary circulations. Scalar hemodynamic targets are used — systemic arterial
+pressure and left-ventricular ejection fraction.
+
+All inputs and targets are in SI units:
+
+- Pressure: Pa
+- Flow: m³/s
+- Resistance: Pa·s/m³
+- Compliance: m³/Pa
+
+## Model
+
+- Four `LinearElastanceChamber` blocks (LV, RV, LA, RA) with `piecewise_cosine` activation
+- Systemic circuit: aortic valve → systemic arteries (`AR_SYS`) → systemic veins (`VEN_SYS`)
+- Pulmonary circuit: pulmonary valve → pulmonary arteries (`AR_PUL`) → pulmonary veins (`VEN_PUL`)
+
+Tunable parameters include cardiac elastances (`LV.Emax`, `RV.Emax`), vascular resistances
+(`AR_SYS.R_poiseuille`), and systemic arterial compliance (`AR_SYS.C`).
+
+## Tuning configurations
+
+| File | Description |
+|---|---|
+| `tuning_nelder_mead.yaml` | Nelder-Mead; scalar systemic pressure + LV EF targets |
+| `tuning_differential_evolution.yaml` | Differential evolution; same targets |
+| `tuning_time_series_target.yaml` | Time-series aortic pressure target (`targets/target_pressure_ar_sys.csv`) |
+| `tuning_complex.yaml` | Larger parameter set with log/max scaling |
+
+## Quick start
+
+Install the package once from the repository root:
+
+```bash
+pip install -e .
+```
+
+Then run from this directory:
+
+1. Baseline inspection:
+
+   ```bash
+   python -c 'from main import run_baseline; run_baseline("model.json")'
+   ```
+
+   Writes `baseline_results/` with time-series CSV, summary CSV, and plots.
+
+2. (Optional) Sensitivity screening to identify influential parameters:
+
+   ```bash
+   svzerodtuner sensitivity-analysis sensitivity.yaml
+   ```
+
+   Writes `sensitivity_results/` with correlation scores and a ranked bar plot.
+
+3. Optimization:
+
+   ```bash
+   svzerodtuner optimize tuning_nelder_mead.yaml
+   ```
+
+## Example outputs
+
+### target_comparison.csv
+
+Each row reports how closely the optimized model matches one target:
+
+| Name | Target | Simulated | Target range | % Error |
+|---|---|---|---|---|
+| Systemic arterial max pressure | 13 065 Pa | ~13 065 Pa | ±10% | ~0 |
+| Systemic arterial min pressure | 7 066 Pa | ~7 066 Pa | ±10% | ~0 |
+| LV ejection fraction | 0.50 | ~0.50 | ±5% | ~0 |
+
+### optimization_history/
+
+| File | Contents |
+|---|---|
+| `objective_history.png` | Objective vs. iteration — confirm the curve flattens before termination |
+| `parameter_evolution.png` | Per-parameter trajectories — flag parameters that converge against a bound |
+| `history.csv` | Full numerical record for post-processing |
+
+### sensitivity_results/
+
+When sensitivity analysis is run first, `sensitivity_results/` contains:
+
+| File | Contents |
+|---|---|
+| `sensitivity_scores.csv` | First-order correlation scores for each parameter × QoI pair |
+| `sensitivity_bar_<qoi>.png` | Ranked bar chart showing which parameters drive each quantity most |
+
+High-scoring parameters are the best candidates to include in the optimization; low-scoring
+parameters can be fixed at baseline values to reduce the search space.
+
+### optimized_simulation/
+
+| File | Contents |
+|---|---|
+| `pressures.png` | Pressure waveforms at key junctions over the final cardiac cycle |
+| `flows.png` | Flow waveforms through key vessels |
+| `volumes.png` | Chamber volume waveforms (LV, RV, LA, RA) |
+| `optimized_results.csv` | Full time-series for every output variable |
+| `optimized_summary.csv` | Min / max / mean / std for every output variable |