design-research-problems

Important

Current monthly release: Axolotl Array - April 2026
Due: April 1, 2026
Tracks: March 2026 work

design-research-problems is a compact library and compendium of design research problems. It packages canonical research prompts, optimization benchmarks, and discrete grammar-style problems behind a small, typed Python API.

Overview

• Five problem families: text, decision, optimization, grammar, and MCP, plus a linked ideation metadata catalog.
• Shared model contracts built around Problem and ComputableProblem, with family-specific subclasses on top.
• A seed catalog that includes 40 ideation prompts plus packaged decision, optimization, grammar, and MCP benchmarks.
• Optional integrations for trussme, pybamm, mcp, Build123d, and external solver backends.
• Typed metadata, a curated public API, runnable examples, and Sphinx docs.

Quickstart

Requires Python 3.12+. Local workflows target Python 3.12 in .python-version.

Create and activate a virtual environment:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

Install in editable mode for local development:

make dev
make test

Or install from PyPI:

pip install design-research-problems

Optional extras:

pip install "design-research-problems[grammar]"
pip install "design-research-problems[battery]"
pip install "design-research-problems[mcp,cad]"
pip install "design-research-problems[solvers,pandas]"

Then inspect the catalog directly from the installed package:

python3 -c "import design_research_problems as derp; print(derp.list_problems())"

And inspect the ideation corpus:

python3 -c "import design_research_problems as derp; print(len(derp.get_ideation_catalog().list_prompts()))"

Launch the packaged desktop GUIs with:

python3 -m design_research_problems.gui --app iot
python3 -m design_research_problems.gui --app truss

The IoT GUI renders a continuous room-temperature colorbar, and the truss GUI only evaluates structurally when the design is not under-determined.

Run one checked-in example from repository root:

PYTHONPATH=src python examples/catalog/list_and_load.py

Examples

Start with examples/README.md for runnable examples across all problem families.

Docs

See the published documentation for quickstart, problem-family guides, generated catalog pages, and API reference.

Build docs locally with:

make docs

Public API

The supported public surface is whatever is exported from design_research_problems.__all__.

Top-level exports include:

• Shared contracts and family bases: Problem, ComputableProblem, ProblemKind, ProblemMetadata, ProblemTaxonomy, Citation, ProblemAsset, TextProblem, DecisionProblem, OptimizationProblem, GrammarProblem, and MCPProblem.
• Family-specific evaluation contracts: DecisionEvaluation, OptimizationEvaluation, and GrammarTransition.
• Catalog access: ProblemRegistry, get_problem, get_problem_as, and list_problems.
• Ideation metadata API: IdeationCatalog, IdeationPromptRecord, IdeationPromptVariant, IdeationPromptFamily, IdeationStudy, EvidenceTier, and get_ideation_catalog.
• Public exceptions: MissingOptionalDependencyError and ProblemEvaluationError.

Contributing

Contribution workflow and quality gates are documented in CONTRIBUTING.md.