design-research-problems 0.1.0__tar.gz

design_research_problems-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Design Research Collective
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

design_research_problems-0.1.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: design-research-problems
+Version: 0.1.0
+Summary: A compendium of canonical design research problems
+Author: The Design Research Collective
+Maintainer-email: "Christopher C. McComb" <ccm@cmu.edu>
+License-Expression: MIT
+Project-URL: Homepage, https://cmudrc.github.io/design-research-problems/
+Project-URL: Documentation, https://cmudrc.github.io/design-research-problems/
+Project-URL: Repository, https://github.com/cmudrc/design-research-problems
+Project-URL: Issues, https://github.com/cmudrc/design-research-problems/issues
+Keywords: design,research,optimization,benchmark,problems
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<3,>=1.26
+Provides-Extra: grammar
+Requires-Dist: trussme>=0.1.0; extra == "grammar"
+Provides-Extra: opt
+Requires-Dist: scipy<2,>=1.11; extra == "opt"
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == "dev"
+Requires-Dist: mypy<2,>=1.10; extra == "dev"
+Requires-Dist: pre-commit<5,>=3.7; extra == "dev"
+Requires-Dist: pytest<9,>=8.2; extra == "dev"
+Requires-Dist: pytest-cov<8,>=7.0; extra == "dev"
+Requires-Dist: ruff<1,>=0.6.0; extra == "dev"
+Requires-Dist: sphinx<9,>=7.4; extra == "dev"
+Requires-Dist: sphinx-rtd-theme<4,>=2.0; extra == "dev"
+Requires-Dist: sphinxcontrib-mermaid<2,>=1.0; extra == "dev"
+Requires-Dist: twine<7,>=5.1; extra == "dev"
+Dynamic: license-file
+
+# design-research-problems
+[![CI](https://github.com/cmudrc/design-research-problems/actions/workflows/ci.yml/badge.svg)](https://github.com/cmudrc/design-research-problems/actions/workflows/ci.yml)
+[![Coverage](https://raw.githubusercontent.com/cmudrc/design-research-problems/main/.github/badges/coverage.svg)](https://github.com/cmudrc/design-research-problems/actions/workflows/ci.yml)
+[![Examples Passing](https://raw.githubusercontent.com/cmudrc/design-research-problems/main/.github/badges/examples-passing.svg)](https://github.com/cmudrc/design-research-problems/actions/workflows/ci.yml)
+[![Public API In Examples](https://raw.githubusercontent.com/cmudrc/design-research-problems/main/.github/badges/examples-api-coverage.svg)](https://github.com/cmudrc/design-research-problems/actions/workflows/ci.yml)
+[![Docs](https://github.com/cmudrc/design-research-problems/actions/workflows/docs-pages.yml/badge.svg)](https://github.com/cmudrc/design-research-problems/actions/workflows/docs-pages.yml)
+
+`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
+
+The initial release centers on three seed problem families:
+
+- Text problems for human-subjects studies and prompt packets
+- Optimization problems with typed bounds and lazy SciPy-backed solving
+- Grammar problems that describe discrete design actions and optional evaluation adapters
+
+The first catalog includes:
+
+- `peanut_sheller_fu2010` for text-based design research
+- `pill_capsule_min_area` for constrained continuous optimization
+- `planar_truss_span` for a discrete topology grammar backed by `trussme`
+
+## Quickstart
+
+Requires Python 3.12+.
+Install from PyPI with:
+
+```bash
+pip install design-research-problems
+```
+
+Install the optional optimization solver support with:
+
+```bash
+pip install "design-research-problems[opt]"
+```
+
+Install the optional `trussme` grammar support with:
+
+```bash
+pip install "design-research-problems[grammar]"
+```
+
+Then inspect the catalog directly from the installed package:
+
+```bash
+python3 -c "from design_research_problems import list_problems; print(list_problems())"
+```
+
+For local development, reproducible installs are pinned to Python `3.12.12` in
+`.python-version`:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+make dev
+make ci
+```
+
+## Docs
+
+See the [published documentation](https://cmudrc.github.io/design-research-problems/)
+for the guide and reference layout.
+Build them locally with:
+
+```bash
+make docs
+```
+
+## Contributing
+
+Contribution guidelines live in
+[CONTRIBUTING.md](https://github.com/cmudrc/design-research-problems/blob/main/CONTRIBUTING.md).

design_research_problems-0.1.0/README.md

@@ -0,0 +1,76 @@
+# design-research-problems
+[![CI](https://github.com/cmudrc/design-research-problems/actions/workflows/ci.yml/badge.svg)](https://github.com/cmudrc/design-research-problems/actions/workflows/ci.yml)
+[![Coverage](https://raw.githubusercontent.com/cmudrc/design-research-problems/main/.github/badges/coverage.svg)](https://github.com/cmudrc/design-research-problems/actions/workflows/ci.yml)
+[![Examples Passing](https://raw.githubusercontent.com/cmudrc/design-research-problems/main/.github/badges/examples-passing.svg)](https://github.com/cmudrc/design-research-problems/actions/workflows/ci.yml)
+[![Public API In Examples](https://raw.githubusercontent.com/cmudrc/design-research-problems/main/.github/badges/examples-api-coverage.svg)](https://github.com/cmudrc/design-research-problems/actions/workflows/ci.yml)
+[![Docs](https://github.com/cmudrc/design-research-problems/actions/workflows/docs-pages.yml/badge.svg)](https://github.com/cmudrc/design-research-problems/actions/workflows/docs-pages.yml)
+
+`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
+
+The initial release centers on three seed problem families:
+
+- Text problems for human-subjects studies and prompt packets
+- Optimization problems with typed bounds and lazy SciPy-backed solving
+- Grammar problems that describe discrete design actions and optional evaluation adapters
+
+The first catalog includes:
+
+- `peanut_sheller_fu2010` for text-based design research
+- `pill_capsule_min_area` for constrained continuous optimization
+- `planar_truss_span` for a discrete topology grammar backed by `trussme`
+
+## Quickstart
+
+Requires Python 3.12+.
+Install from PyPI with:
+
+```bash
+pip install design-research-problems
+```
+
+Install the optional optimization solver support with:
+
+```bash
+pip install "design-research-problems[opt]"
+```
+
+Install the optional `trussme` grammar support with:
+
+```bash
+pip install "design-research-problems[grammar]"
+```
+
+Then inspect the catalog directly from the installed package:
+
+```bash
+python3 -c "from design_research_problems import list_problems; print(list_problems())"
+```
+
+For local development, reproducible installs are pinned to Python `3.12.12` in
+`.python-version`:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+make dev
+make ci
+```
+
+## Docs
+
+See the [published documentation](https://cmudrc.github.io/design-research-problems/)
+for the guide and reference layout.
+Build them locally with:
+
+```bash
+make docs
+```
+
+## Contributing
+
+Contribution guidelines live in
+[CONTRIBUTING.md](https://github.com/cmudrc/design-research-problems/blob/main/CONTRIBUTING.md).

design_research_problems-0.1.0/pyproject.toml

@@ -0,0 +1,118 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "design-research-problems"
+version = "0.1.0"
+description = "A compendium of canonical design research problems"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "The Design Research Collective" }]
+maintainers = [{ name = "Christopher C. McComb", email = "ccm@cmu.edu" }]
+keywords = ["design", "research", "optimization", "benchmark", "problems"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Operating System :: OS Independent",
+  "Topic :: Scientific/Engineering",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+dependencies = [
+  "numpy>=1.26,<3",
+]
+
+[project.urls]
+Homepage = "https://cmudrc.github.io/design-research-problems/"
+Documentation = "https://cmudrc.github.io/design-research-problems/"
+Repository = "https://github.com/cmudrc/design-research-problems"
+Issues = "https://github.com/cmudrc/design-research-problems/issues"
+
+[project.optional-dependencies]
+grammar = ["trussme>=0.1.0"]
+opt = ["scipy>=1.11,<2"]
+dev = [
+  "build>=1.2,<2",
+  "mypy>=1.10,<2",
+  "pre-commit>=3.7,<5",
+  "pytest>=8.2,<9",
+  "pytest-cov>=7.0,<8",
+  "ruff>=0.6.0,<1",
+  "sphinx>=7.4,<9",
+  "sphinx-rtd-theme>=2.0,<4",
+  "sphinxcontrib-mermaid>=1.0,<2",
+  "twine>=5.1,<7",
+]
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+design_research_problems = [
+  "py.typed",
+  "_assets/catalog/*/*.toml",
+  "_assets/catalog/*/*.md",
+  "_assets/catalog/*/*.bib",
+]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]
+markers = [
+  "examples_full: deterministic example execution suite",
+  "examples_smoke: lightweight example smoke checks",
+  "trussme_real: tests that require an installed trussme package",
+]
+
+[tool.ruff]
+line-length = 120
+target-version = "py312"
+src = ["src", "tests", "examples", "scripts"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF", "D"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*.py" = ["D"]
+"examples/**/*.py" = ["D"]
+"scripts/*.py" = ["D"]
+
+[tool.mypy]
+packages = ["design_research_problems"]
+python_version = "3.12"
+warn_unused_configs = true
+check_untyped_defs = true
+disallow_untyped_defs = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_return_any = true
+strict_equality = true
+
+[[tool.mypy.overrides]]
+module = [
+  "scipy",
+  "scipy.*",
+  "trussme",
+  "trussme.*",
+]
+ignore_missing_imports = true

design_research_problems-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

design_research_problems-0.1.0/src/design_research_problems/__init__.py

@@ -0,0 +1,73 @@
+"""Curated public package interface with lazily resolved exports."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+from typing import TYPE_CHECKING, Final
+
+from design_research_problems._lazy_exports import module_dir, resolve_lazy_export
+
+_EXPORTS: Final[dict[str, str]] = {
+    "ProblemKind": "design_research_problems.problems:ProblemKind",
+    "ProblemMetadata": "design_research_problems.problems:ProblemMetadata",
+    "ProblemTaxonomy": "design_research_problems.problems:ProblemTaxonomy",
+    "Citation": "design_research_problems.problems:Citation",
+    "ProblemAsset": "design_research_problems.problems:ProblemAsset",
+    "TextProblem": "design_research_problems.problems:TextProblem",
+    "OptimizationProblem": "design_research_problems.problems:OptimizationProblem",
+    "GrammarProblem": "design_research_problems.problems:GrammarProblem",
+    "ProblemRegistry": "design_research_problems._catalog:ProblemRegistry",
+    "MissingOptionalDependencyError": "design_research_problems._exceptions:MissingOptionalDependencyError",
+    "ProblemEvaluationError": "design_research_problems._exceptions:ProblemEvaluationError",
+    "get_problem": "design_research_problems._catalog:get_problem",
+    "list_problems": "design_research_problems._catalog:list_problems",
+}
+
+__all__ = ["__version__", *_EXPORTS.keys()]
+
+try:
+    __version__ = version("design-research-problems")
+except PackageNotFoundError:
+    __version__ = "0+unknown"
+
+
+def __getattr__(name: str) -> object:
+    """Resolve and cache one deferred public export.
+
+    Args:
+        name: Public symbol name requested from the package module.
+
+    Returns:
+        Resolved export object.
+    """
+    return resolve_lazy_export(
+        module_name=__name__,
+        exports=_EXPORTS,
+        export_name=name,
+        namespace=globals(),
+    )
+
+
+def __dir__() -> list[str]:
+    """Return package attributes, including deferred exports.
+
+    Returns:
+        Sorted attribute list for interactive discovery.
+    """
+    return module_dir(globals(), __all__)
+
+
+if TYPE_CHECKING:
+    from ._catalog import ProblemRegistry as ProblemRegistry
+    from ._catalog import get_problem as get_problem
+    from ._catalog import list_problems as list_problems
+    from ._exceptions import MissingOptionalDependencyError as MissingOptionalDependencyError
+    from ._exceptions import ProblemEvaluationError as ProblemEvaluationError
+    from .problems import Citation as Citation
+    from .problems import GrammarProblem as GrammarProblem
+    from .problems import OptimizationProblem as OptimizationProblem
+    from .problems import ProblemAsset as ProblemAsset
+    from .problems import ProblemKind as ProblemKind
+    from .problems import ProblemMetadata as ProblemMetadata
+    from .problems import ProblemTaxonomy as ProblemTaxonomy
+    from .problems import TextProblem as TextProblem

design_research_problems-0.1.0/src/design_research_problems/_assets/catalog/peanut_sheller_fu2010/citation.bib

@@ -0,0 +1,5 @@
+@article{fu2010design,
+  title={Design team convergence: the influence of example solution quality},
+  author={Fu, Katherine and Cagan, Jonathan and Kotovsky, Kenneth},
+  year={2010}
+}

design_research_problems-0.1.0/src/design_research_problems/_assets/catalog/peanut_sheller_fu2010/problem.toml

@@ -0,0 +1,26 @@
+problem_id = "peanut_sheller_fu2010"
+title = "Design Problem - Device to shell peanuts"
+summary = "A text-based design prompt about a low-cost peanut sheller for small-scale farmers."
+kind = "text"
+statement_file = "statement.md"
+citation_file = "citation.bib"
+citation_key = "fu2010design"
+citation_kind = "bibtex"
+feature_flags = [
+  "statement-markdown",
+  "citation-backed",
+  "prompt-packet",
+  "human-subjects-ready",
+]
+
+[taxonomy]
+formulation = "textual_prompt"
+convexity = "not_applicable"
+design_variable_type = "not_applicable"
+is_dynamic = false
+orientation = "engineering_practical"
+feasibility_ratio_hint = 1.0
+objective_mode = "qualitative"
+constraint_nature = "informal"
+bounds_summary = "not_applicable"
+tags = ["text", "human-subjects", "agriculture", "mechanical-design"]

design_research_problems-0.1.0/src/design_research_problems/_assets/catalog/peanut_sheller_fu2010/statement.md

@@ -0,0 +1,18 @@
+# Design Problem - Device to shell peanuts
+
+In places like Haiti and certain West African countries, peanuts are a
+significant crop. Most peanut farmers shell their peanuts by hand, an
+inefficient and labor-intensive process. Our goal is to build a low-cost,
+easy to manufacture peanut sheller targeted at individuals and small
+cooperatives that will increase the productivity of the peanut farmers.
+Further, this peanut sheller should be manufacturable with materials that are
+readily available in the target communities. Our target throughput is
+approximately 50 kg (110 lbs) per hour.
+
+# Customer Needs
+
+- Must remove the shell with minimal damage to the peanuts.
+- Electrical outlets are not available as a power source.
+- A large quantity of peanuts must be quickly shelled.
+- Low cost.
+- Easy to manufacture.

design_research_problems-0.1.0/src/design_research_problems/_assets/catalog/pill_capsule_min_area/problem.toml

@@ -0,0 +1,28 @@
+problem_id = "pill_capsule_min_area"
+title = "Pill capsule minimum-area problem"
+summary = "A two-variable constrained optimization problem that minimizes capsule surface area at fixed volume."
+kind = "optimization"
+statement_file = "statement.md"
+implementation = "design_research_problems.problems.optimization._pill:PillCapsuleMinArea"
+feature_flags = [
+  "statement-markdown",
+  "bounded-variables",
+  "equality-constraint",
+  "seeded-data-generation",
+  "optional-solver",
+]
+
+[parameters]
+required_volume = 1e-6
+
+[taxonomy]
+formulation = "nonlinear_program"
+convexity = "not_guaranteed"
+design_variable_type = "continuous"
+is_dynamic = false
+orientation = "mathematical"
+feasibility_ratio_hint = 0.5
+objective_mode = "single"
+constraint_nature = "hard"
+bounds_summary = "radius and length bounded on [0, 1]"
+tags = ["optimization", "continuous", "nonlinear", "single-objective"]

design_research_problems-0.1.0/src/design_research_problems/_assets/catalog/pill_capsule_min_area/statement.md

@@ -0,0 +1,8 @@
+# Pill capsule minimum-area problem
+
+Minimize the surface area of a capsule-shaped pill while satisfying a fixed
+volume requirement. The design variables are the capsule radius and cylindrical
+section length. Both variables are bounded on [0, 1].
+
+This seed problem is a compact constrained optimization benchmark for design
+research workflows and solver experiments.

design_research_problems-0.1.0/src/design_research_problems/_assets/catalog/planar_truss_span/problem.toml

@@ -0,0 +1,30 @@
+problem_id = "planar_truss_span"
+title = "Planar truss span grammar problem"
+summary = "A discrete topology grammar for adding and removing joints and members in a planar truss."
+kind = "grammar"
+statement_file = "statement.md"
+implementation = "design_research_problems.problems.grammar._planar_truss:PlanarTrussSpanProblem"
+feature_flags = [
+  "statement-markdown",
+  "serializable-state",
+  "discrete-actions",
+  "optional-evaluator",
+  "external-adapter",
+]
+
+[parameters]
+span = 10.0
+max_height = 5.0
+load_magnitude = 1000.0
+
+[taxonomy]
+formulation = "discrete_grammar"
+convexity = "not_applicable"
+design_variable_type = "discrete"
+is_dynamic = false
+orientation = "engineering_practical"
+feasibility_ratio_hint = 0.25
+objective_mode = "single"
+constraint_nature = "hard"
+bounds_summary = "planar topology over a fixed span and height envelope"
+tags = ["grammar", "truss", "discrete", "topology"]

design_research_problems-0.1.0/src/design_research_problems/_assets/catalog/planar_truss_span/statement.md

@@ -0,0 +1,10 @@
+# Planar truss span grammar problem
+
+Create a stable, lightweight planar truss spanning a fixed distance between a
+left pinned support and a right roller support. The grammar begins with the
+supports and one loaded free joint. Designers can add interior joints, add
+members, and remove members.
+
+States are evaluated by translating the library-owned grammar state into a
+fresh `trussme.Truss`, applying the load, and attempting a structural
+analysis. Singular or unstable states are treated as infeasible results.

design_research_problems-0.1.0/src/design_research_problems/_catalog/__init__.py

@@ -0,0 +1,5 @@
+"""Catalog loading and registry exports."""
+
+from ._registry import ProblemRegistry, get_problem, list_problems
+
+__all__ = ["ProblemRegistry", "get_problem", "list_problems"]