Add DCC'26 workshop notebook suite (participant + solutions)

.gitignore

@@ -171,3 +171,5 @@ logs/*
 
 .ruff_cache/
 engibench_studies/*
+workshops/dcc26/artifacts/*
+workshops/dcc26/optional_artifacts/*

README.md

@@ -109,6 +109,21 @@ We have some colab notebooks that show how to use some of the EngiBench/EngiOpt
 * [Example easy model (GAN)](https://colab.research.google.com/github/IDEALLab/EngiOpt/blob/main/example_easy_model.ipynb)
 * [Example hard model (Diffusion)](https://colab.research.google.com/github/IDEALLab/EngiOpt/blob/main/example_hard_model.ipynb)
 
+## Workshop notebooks
+
+For the DCC'26 hands-on tutorial flow, see:
+
+- `workshops/dcc26/participant/00_setup_api_warmup.ipynb`
+- `workshops/dcc26/participant/01_train_generate.ipynb`
+- `workshops/dcc26/participant/02_evaluate_metrics.ipynb`
+- `workshops/dcc26/participant/03_add_new_problem_scaffold.ipynb`
+
+Facilitator solutions are in:
+
+- `workshops/dcc26/solutions/`
+
+See `workshops/dcc26/README.md` for agenda mapping, fallback path, and artifact outputs.
+
 
 ## Citing
 

pyproject.toml

@@ -113,6 +113,10 @@ target-version = "py39"
 ######################################## LINTING ########################################
 [tool.ruff.lint]
 select = ["ALL"]
+exclude = [
+  "workshops/dcc26/**/*.ipynb",
+  "workshops/dcc26/utils/**/*.py",
+]
 ignore = [
   "ANN",      # flake8-annotations (mypy's job)
   "COM812",   # missing-trailing-comma (conflicts with formatter)

workshops/dcc26/NOTEBOOK_PEDAGOGY_BLUEPRINT.md

@@ -0,0 +1,131 @@
+# DCC26 Notebook Pedagogy Blueprint (Pre-write Source)
+
+This document is the canonical pre-write for workshop notebooks. Notebooks should be generated from this structure, not authored directly as raw `.ipynb` first.
+
+## Teaching Design Principles
+
+1. Every technical step is paired with a markdown teaching cell.
+2. Every code section has local context: why, inputs, outputs, checks, failure modes.
+3. Benchmark science is explicit: objective, feasibility, diversity, novelty, reproducibility.
+4. Discussion prompts are embedded and mapped to workshop breakout questions.
+5. Participant and solution tracks share the same pedagogical arc; only implementation detail differs.
+
+## Common Cell Pattern
+
+For each section:
+
+- Purpose: why this step matters for benchmark credibility
+- Inputs: what artifacts/variables are required
+- Action: code operation performed
+- Success check: what output indicates correctness
+- Failure modes: common pitfalls and fixes
+- Discussion bridge: one reflection question
+
+---
+
+## Notebook 00: Setup + API Warmup
+
+### Learning objective
+Understand EngiBench benchmark contract components and reproducibility controls.
+
+### Section plan
+1. Read-me-first + copy mode + runtime expectation
+2. Concept cell: EngiBench vs model libraries
+3. Environment bootstrap
+4. Reproducibility cell (seed, versions)
+5. Problem instantiation (`Beams2D`) + inspection
+6. Dataset inspection and shape sanity
+7. Render one sample and explain representation
+8. Explicit constraint violation check with interpretation
+9. Reflection prompts tied to comparability across papers
+
+### Discussion trigger
+Which benchmark settings must be fixed for fair method comparison?
+
+---
+
+## Notebook 01: Train + Generate
+
+### Learning objective
+Implement an EngiOpt model against EngiBench data while preserving evaluation-ready artifacts.
+
+### Section plan
+1. Read-me-first + copy mode + expected runtime
+2. Concept cell: inverse design framing, conditional generation assumptions
+3. Bootstrap deps and imports
+4. Configuration and artifact contract
+5. Data subset construction and rationale (runtime vs fidelity)
+6. Model definition and optimizer
+7. Training loop with diagnostics + expected loss behavior
+8. Generation from test conditions
+9. Quick feasibility precheck (not final evaluation)
+10. Artifact export contract (npy/json/checkpoint/history/curve)
+11. Optional W&B logging: train curve, scalar logs, artifact bundle
+12. Visual sanity grid
+13. Discussion prompt: training loss vs engineering validity mismatch
+
+### Discussion trigger
+Can lower train reconstruction loss worsen simulator objective or feasibility?
+
+---
+
+## Notebook 02: Evaluate + Metrics
+
+### Learning objective
+Run robust benchmark evaluation and interpret trade-offs beyond objective score.
+
+### Section plan
+1. Read-me-first + copy mode + expected runtime
+2. Concept cell: why objective-only reporting is incomplete
+3. Bootstrap deps and imports
+4. Artifact loading strategy (local -> optional W&B -> local auto-build)
+5. Per-sample evaluation loop (constraint + simulate)
+6. Metric layer:
+   - objective means and gap
+   - improvement rate
+   - feasibility/violation rates
+   - diversity proxy
+   - novelty-to-train proxy
+7. Export layer: CSV + histogram + scatter + grid
+8. Optional W&B evaluation logging (table + images + summary)
+9. Interpretation rubric with examples
+10. Breakout prompts mapped to workshop proposal
+
+### Discussion trigger
+Which missing metric would change conclusions for your domain?
+
+---
+
+## Notebook 03: Add New Problem Scaffold
+
+### Learning objective
+Understand minimal interface required for a reusable EngiBench-style benchmark problem.
+
+### Section plan
+1. Read-me-first + copy mode
+2. Concept cell: benchmark-ready problem checklist
+3. Scaffold imports and abstract contract explanation
+4. Minimal `Problem` implementation skeleton
+5. Toy simulator and constraints
+6. Registration/discovery and deterministic behavior
+7. Contribution checklist for real domains
+8. Reflection prompts on leakage, units, and reproducibility metadata
+
+### Discussion trigger
+What metadata is minimally required so another lab can reproduce your new benchmark?
+
+---
+
+## Participant vs Solution Policy
+
+- Participant notebooks: keep code TODOs, but each TODO has explicit completion checks and expected outputs.
+- Solution notebooks: complete implementations plus concise inline comments for non-obvious logic only.
+- Both tracks: keep identical markdown structure for pedagogical alignment.
+
+## Quality Gate Before Publishing
+
+1. All code cells compile.
+2. Solution Notebook 01+02 execute end-to-end in workshop env.
+3. Artifact contract is consistent between Notebook 01 and 02.
+4. Copy-safe links use `#copy=true`.
+5. Standalone readability check: each notebook understandable without live lecture.

workshops/dcc26/README.md

@@ -0,0 +1,104 @@
+# DCC 2026 Workshop Notebook Suite
+
+This folder contains the DCC'26 hands-on notebook suite for benchmarking AI methods in engineering design with EngiBench and EngiOpt.
+
+It is split into two tracks:
+
+- `participant/`: notebooks with guided `PUBLIC FILL-IN` cells for attendees
+- `solutions/`: fully completed facilitator notebooks
+
+## Workshop flow (3.5h)
+
+- `participant/00_setup_api_warmup.ipynb` and `solutions/00_setup_api_warmup.ipynb` (10-15 min)
+  - Environment setup
+  - Problem + dataset inspection
+  - Rendering and constraint checks
+
+- `participant/01_train_generate.ipynb` and `solutions/01_train_generate.ipynb` (30 min)
+  - Lightweight training using `engiopt.cgan_2d.Generator`
+  - Deterministic seeds
+  - Artifact export for downstream evaluation (runtime/W&B optional transport)
+
+- `participant/02_evaluate_metrics.ipynb` and `solutions/02_evaluate_metrics.ipynb` (20 min)
+  - Constraint validation
+  - Physics simulation
+  - Baseline comparison
+  - Metric and artifact export
+
+- `participant/03_add_new_problem_scaffold.ipynb` and `solutions/03_add_new_problem_scaffold.ipynb` (25 min)
+  - Ambitious `Problem` scaffold (`PlanarManipulatorCoDesignProblem`, not currently in EngiBench)
+  - PyBullet-based robotics co-design simulation and optimization loop
+  - Mapping to contribution docs
+
+## Runtime assumptions
+
+- Primary live problem: `Beams2D`
+- No container-dependent problems are required during workshop exercises
+- W&B integration is optional and disabled by default
+
+## Colab setup
+
+Use `requirements-colab.txt` only as a local convenience snapshot.
+The notebook bootstrap cells are the runtime source of truth for Colab.
+
+All notebooks now include a conditional dependency bootstrap cell:
+
+- On Colab: installs required packages automatically.
+- On local envs: skips install by default (`FORCE_INSTALL = False`).
+- Note: notebooks that use EngiOpt install it from the EngiOpt GitHub branch bootstrap.
+
+## Open in Colab
+
+Use these `?copy=true` links for workshop sharing so attendees are prompted to create their own Drive copy first.
+
+- Participant 00: https://colab.research.google.com/github/IDEALLab/EngiOpt/blob/codex/dcc26-workshop-notebooks/workshops/dcc26/participant/00_setup_api_warmup.ipynb?copy=true
+- Participant 01: https://colab.research.google.com/github/IDEALLab/EngiOpt/blob/codex/dcc26-workshop-notebooks/workshops/dcc26/participant/01_train_generate.ipynb?copy=true
+- Participant 02: https://colab.research.google.com/github/IDEALLab/EngiOpt/blob/codex/dcc26-workshop-notebooks/workshops/dcc26/participant/02_evaluate_metrics.ipynb?copy=true
+- Participant 03: https://colab.research.google.com/github/IDEALLab/EngiOpt/blob/codex/dcc26-workshop-notebooks/workshops/dcc26/participant/03_add_new_problem_scaffold.ipynb?copy=true
+- Solution 00: https://colab.research.google.com/github/IDEALLab/EngiOpt/blob/codex/dcc26-workshop-notebooks/workshops/dcc26/solutions/00_setup_api_warmup.ipynb?copy=true
+- Solution 01: https://colab.research.google.com/github/IDEALLab/EngiOpt/blob/codex/dcc26-workshop-notebooks/workshops/dcc26/solutions/01_train_generate.ipynb?copy=true
+- Solution 02: https://colab.research.google.com/github/IDEALLab/EngiOpt/blob/codex/dcc26-workshop-notebooks/workshops/dcc26/solutions/02_evaluate_metrics.ipynb?copy=true
+- Solution 03: https://colab.research.google.com/github/IDEALLab/EngiOpt/blob/codex/dcc26-workshop-notebooks/workshops/dcc26/solutions/03_add_new_problem_scaffold.ipynb?copy=true
+
+## Output artifacts
+
+By default, solution notebooks write generated artifacts to:
+
+- Local/Jupyter: `workshops/dcc26/artifacts/`
+- Google Colab runtime: `/content/dcc26_artifacts/` (no Google Drive permission needed)
+
+Optional:
+
+- You can enable W&B artifact upload/download in Notebook 01/02 by setting `USE_WANDB_ARTIFACTS = True`.
+- Notebook 01 logs training dynamics (`train/loss`) and can upload checkpoint/history/plots as artifact payload.
+- Notebook 02 can log evaluation metrics, tables, and figures to W&B.
+- W&B is disabled by default so participants can run without account setup or API keys.
+- Notebook 02 auto-builds Notebook 01-style artifacts locally with EngiOpt if they are missing (`AUTO_BUILD_ARTIFACTS_IF_MISSING = True`).
+
+These include:
+
+- `generated_designs.npy`
+- `baseline_designs.npy`
+- `conditions.json`
+- `engiopt_cgan2d_generator_supervised.pt`
+- `training_history.csv`
+- `training_curve.png`
+- `metrics_summary.csv`
+- `objective_histogram.png`
+- `objective_scatter.png`
+- `design_grid.png`
+
+## Facilitator fallback policy
+
+If runtime is constrained:
+
+1. Skip Notebook 01 and run `02_evaluate_metrics.ipynb`; it can build required artifacts automatically.
+2. Or reuse a previously saved checkpoint/artifact set from W&B or local runtime files.
+3. Keep `03_add_new_problem_scaffold.ipynb` as the capstone for extensibility.
+
+## Suggested pre-workshop checks
+
+1. Run all notebooks once in fresh Colab runtime.
+2. Confirm dataset download succeeds.
+3. Confirm artifacts are generated in the expected folder.
+4. Confirm no cell requires W&B auth unless explicitly enabled.