# caelan/pb-construction architecture

> Architecture diagram of the GitHub repository caelan/pb-construction, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/caelan/pb-construction
- Repository: https://github.com/caelan/pb-construction

## Overview

pb-construction is a PyBullet-based construction-planning research application. The main workflow loads an extrusion structure, searches for a feasible print order, checks structural stability and robot motion/collisions, then visualizes or executes the resulting plan. The graph also preserves documented pick-and-place and robot/structural-analysis capabilities. Edges reflect README statements or relationships listed in the SOURCE INDEX; unsampled integration details are left unconnected or marked unverified.

Main entry points: [`extrusion/heuristics.py`](https://github.com/caelan/pb-construction/blob/master/extrusion/heuristics.py) (Search heuristics), [`extrusion/run.py`](https://github.com/caelan/pb-construction/blob/master/extrusion/run.py) (Extrusion CLI), [`extrusion/progression.py`](https://github.com/caelan/pb-construction/blob/master/extrusion/progression.py) (Progression search), [`extrusion/experiment.py`](https://github.com/caelan/pb-construction/blob/master/extrusion/experiment.py) (Experiment runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_planning["Planning and orchestration"]
  node_extrusion_run["Extrusion CLI<br/>[run.py]"]
  node_experiment["Experiment runner<br/>[experiment.py]"]
  node_progression["Progression search<br/>[progression.py]"]
  node_regression["Regression search<br/>[regression.py]"]
  node_lookahead["Lookahead search<br/>[lookahead.py]"]
  node_temporal["Temporal planning<br/>[temporal.py]"]
  node_stripstream["Stream planning<br/>[stripstream.py]"]
  node_heuristics["Search heuristics<br/>[heuristics.py]"]
  node_tsp["Sequence optimization<br/>[tsp.py]"]
end

subgraph group_robotics["Robot and print feasibility"]
  node_stream["Print trajectory sampler<br/>[stream.py]"]
  node_motion["Robot motion planner<br/>[motion.py]"]
  node_validator["Plan validator<br/>[validator.py]"]
  node_picknplace["Pick-place example<br/>[run.py]"]
end

subgraph group_structure["Structural analysis"]
  node_stiffness["Stiffness checker<br/>[stiffness.py]"]
  node_equilibrium["Equilibrium analysis<br/>[equilibrium.py]"]
end

subgraph group_interfaces["Inputs and results"]
  node_parsing["Structure parser<br/>[parsing.py]"]
  node_visualization["Plan visualization<br/>[visualization.py]"]
  node_analysis["Experiment analysis<br/>[analyze.py]"]
end

node_user(("Planner user"))
node_robot_stack["PyBullet robot stack"]
node_conmech["ConMech integration"]
node_experiment_data["Experiment records"]

node_user -->|"starts example"| node_extrusion_run
node_user -->|"starts example"| node_picknplace
node_extrusion_run -->|"loads structures"| node_parsing
node_extrusion_run -->|"dispatches search"| node_progression
node_extrusion_run -->|"dispatches search"| node_regression
node_extrusion_run -->|"dispatches search"| node_lookahead
node_extrusion_run -->|"renders results"| node_visualization
node_experiment -->|"runs algorithm"| node_progression
node_experiment -->|"runs algorithm"| node_lookahead
node_experiment -->|"selects heuristics"| node_heuristics
node_progression -->|"scores candidates"| node_heuristics
node_progression -->|"plans transit"| node_motion
node_regression -->|"plans transit"| node_motion
node_regression -->|"scores candidates"| node_heuristics
node_lookahead -->|"validates plans"| node_validator
node_lookahead -->|"samples prints"| node_stream
node_lookahead -->|"reuses search"| node_progression
node_temporal -->|"requests print samples"| node_stream
node_temporal -->|"uses distances"| node_heuristics
node_stripstream -->|"uses temporal planning"| node_temporal
node_stripstream -->|"uses heuristics"| node_heuristics
node_heuristics -->|"computes reactions"| node_equilibrium
node_heuristics -->|"loads structure"| node_parsing
node_heuristics -->|"evaluates deformation"| node_stiffness
node_stream -.->|"uses PyBullet tools"| node_robot_stack
node_motion -.->|"plans robot motion"| node_robot_stack
node_progression -->|"tests stability"| node_stiffness
node_regression -->|"tests stability"| node_stiffness
node_stiffness -->|"uses optional solver"| node_conmech
node_visualization -->|"draws reactions"| node_equilibrium
node_experiment -.->|"records trials"| node_experiment_data
node_analysis -->|"reads experiment results"| node_experiment
node_analysis -->|"loads structure data"| node_parsing
node_analysis -->|"uses figures"| node_visualization
node_picknplace -.->|"uses robot examples"| node_robot_stack
node_heuristics -->|"uses sequence costs"| node_tsp

click node_extrusion_run "https://github.com/caelan/pb-construction/blob/master/extrusion/run.py"
click node_experiment "https://github.com/caelan/pb-construction/blob/master/extrusion/experiment.py"
click node_progression "https://github.com/caelan/pb-construction/blob/master/extrusion/progression.py"
click node_regression "https://github.com/caelan/pb-construction/blob/master/extrusion/regression.py"
click node_lookahead "https://github.com/caelan/pb-construction/blob/master/extrusion/lookahead.py"
click node_temporal "https://github.com/caelan/pb-construction/blob/master/extrusion/temporal.py"
click node_stripstream "https://github.com/caelan/pb-construction/blob/master/extrusion/stripstream.py"
click node_parsing "https://github.com/caelan/pb-construction/blob/master/extrusion/parsing.py"
click node_heuristics "https://github.com/caelan/pb-construction/blob/master/extrusion/heuristics.py"
click node_tsp "https://github.com/caelan/pb-construction/blob/master/extrusion/tsp.py"
click node_stream "https://github.com/caelan/pb-construction/blob/master/extrusion/stream.py"
click node_motion "https://github.com/caelan/pb-construction/blob/master/extrusion/motion.py"
click node_validator "https://github.com/caelan/pb-construction/blob/master/extrusion/validator.py"
click node_stiffness "https://github.com/caelan/pb-construction/blob/master/extrusion/stiffness.py"
click node_equilibrium "https://github.com/caelan/pb-construction/blob/master/extrusion/equilibrium.py"
click node_visualization "https://github.com/caelan/pb-construction/blob/master/extrusion/visualization.py"
click node_analysis "https://github.com/caelan/pb-construction/blob/master/extrusion/analyze.py"
click node_picknplace "https://github.com/caelan/pb-construction/blob/master/picknplace/run.py"
click node_robot_stack "https://github.com/caelan/pb-construction/tree/master/conrob_pybullet"
click node_conmech "https://github.com/caelan/pb-construction/tree/master/conmech"
click node_experiment_data "https://github.com/caelan/pb-construction/tree/master/experiments"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_extrusion_run,node_experiment,node_progression,node_regression,node_lookahead,node_temporal,node_stripstream,node_heuristics,node_tsp,node_user toneBlue
class node_stream,node_motion,node_validator,node_picknplace toneAmber
class node_stiffness,node_equilibrium toneMint
class node_parsing,node_visualization,node_analysis toneRose
class node_robot_stack,node_experiment_data toneTeal
class node_conmech toneIndigo
```

## Components

### Planning and orchestration

- [Extrusion CLI](https://github.com/caelan/pb-construction/blob/master/extrusion/run.py): `extrusion/run.py`
- [Experiment runner](https://github.com/caelan/pb-construction/blob/master/extrusion/experiment.py): `extrusion/experiment.py`
- [Progression search](https://github.com/caelan/pb-construction/blob/master/extrusion/progression.py): `extrusion/progression.py`
- [Regression search](https://github.com/caelan/pb-construction/blob/master/extrusion/regression.py): `extrusion/regression.py`
- [Lookahead search](https://github.com/caelan/pb-construction/blob/master/extrusion/lookahead.py): `extrusion/lookahead.py`
- [Temporal planning](https://github.com/caelan/pb-construction/blob/master/extrusion/temporal.py): `extrusion/temporal.py`
- [Stream planning](https://github.com/caelan/pb-construction/blob/master/extrusion/stripstream.py): `extrusion/stripstream.py`
- [Search heuristics](https://github.com/caelan/pb-construction/blob/master/extrusion/heuristics.py): `extrusion/heuristics.py`
- [Sequence optimization](https://github.com/caelan/pb-construction/blob/master/extrusion/tsp.py): `extrusion/tsp.py`

### Robot and print feasibility

- [Print trajectory sampler](https://github.com/caelan/pb-construction/blob/master/extrusion/stream.py): `extrusion/stream.py`
- [Robot motion planner](https://github.com/caelan/pb-construction/blob/master/extrusion/motion.py): `extrusion/motion.py`
- [Plan validator](https://github.com/caelan/pb-construction/blob/master/extrusion/validator.py): `extrusion/validator.py`
- [Pick-place example](https://github.com/caelan/pb-construction/blob/master/picknplace/run.py): `picknplace/run.py`

### Structural analysis

- [Stiffness checker](https://github.com/caelan/pb-construction/blob/master/extrusion/stiffness.py): `extrusion/stiffness.py`
- [Equilibrium analysis](https://github.com/caelan/pb-construction/blob/master/extrusion/equilibrium.py): `extrusion/equilibrium.py`

### Inputs and results

- [Structure parser](https://github.com/caelan/pb-construction/blob/master/extrusion/parsing.py): `extrusion/parsing.py`
- [Plan visualization](https://github.com/caelan/pb-construction/blob/master/extrusion/visualization.py): `extrusion/visualization.py`
- [Experiment analysis](https://github.com/caelan/pb-construction/blob/master/extrusion/analyze.py): `extrusion/analyze.py`

### Other components

- **Planner user**
- [PyBullet robot stack](https://github.com/caelan/pb-construction/tree/master/conrob_pybullet): `conrob_pybullet`
- [ConMech integration](https://github.com/caelan/pb-construction/tree/master/conmech): `conmech`
- [Experiment records](https://github.com/caelan/pb-construction/tree/master/experiments): `experiments`

## Connections

- Planner user → Extrusion CLI: starts example (evidence: `README.md`)
- Planner user → Pick-place example: starts example (evidence: `README.md`)
- Extrusion CLI → Structure parser: loads structures (evidence: `extrusion/run.py`)
- Extrusion CLI → Progression search: dispatches search (evidence: `extrusion/run.py`)
- Extrusion CLI → Regression search: dispatches search (evidence: `extrusion/run.py`)
- Extrusion CLI → Lookahead search: dispatches search (evidence: `extrusion/run.py`)
- Extrusion CLI → Plan visualization: renders results (evidence: `extrusion/run.py`)
- Experiment runner → Progression search: runs algorithm (evidence: `extrusion/experiment.py`)
- Experiment runner → Lookahead search: runs algorithm (evidence: `extrusion/experiment.py`)
- Experiment runner → Search heuristics: selects heuristics (evidence: `extrusion/experiment.py`)
- Progression search → Search heuristics: scores candidates (evidence: `extrusion/progression.py`)
- Progression search → Robot motion planner: plans transit (evidence: `extrusion/progression.py`)
- Regression search → Robot motion planner: plans transit (evidence: `extrusion/regression.py`)
- Regression search → Search heuristics: scores candidates (evidence: `extrusion/regression.py`)
- Lookahead search → Plan validator: validates plans (evidence: `extrusion/lookahead.py`)
- Lookahead search → Print trajectory sampler: samples prints (evidence: `extrusion/lookahead.py`)
- Lookahead search → Progression search: reuses search (evidence: `extrusion/lookahead.py`)
- Temporal planning → Print trajectory sampler: requests print samples (evidence: `extrusion/temporal.py`)
- Temporal planning → Search heuristics: uses distances (evidence: `extrusion/temporal.py`)
- Stream planning → Temporal planning: uses temporal planning (evidence: `extrusion/stripstream.py`)
- Stream planning → Search heuristics: uses heuristics (evidence: `extrusion/stripstream.py`)
- Search heuristics → Equilibrium analysis: computes reactions (evidence: `extrusion/heuristics.py`)
- Search heuristics → Structure parser: loads structure (evidence: `extrusion/heuristics.py`)
- Search heuristics → Stiffness checker: evaluates deformation (evidence: `extrusion/heuristics.py`)
- Print trajectory sampler → PyBullet robot stack: uses PyBullet tools
- Robot motion planner → PyBullet robot stack: plans robot motion
- Progression search → Stiffness checker: tests stability (evidence: `extrusion/progression.py`)
- Regression search → Stiffness checker: tests stability (evidence: `extrusion/regression.py`)
- Stiffness checker → ConMech integration: uses optional solver (evidence: `extrusion/stiffness.py`)
- Plan visualization → Equilibrium analysis: draws reactions (evidence: `extrusion/visualization.py`)
- Experiment runner → Experiment records: records trials
- Experiment analysis → Experiment runner: reads experiment results (evidence: `extrusion/analyze.py`)
- Experiment analysis → Structure parser: loads structure data (evidence: `extrusion/analyze.py`)
- Experiment analysis → Plan visualization: uses figures (evidence: `extrusion/analyze.py`)
- Pick-place example → PyBullet robot stack: uses robot examples
- Search heuristics → Sequence optimization: uses sequence costs (evidence: `extrusion/heuristics.py`)
