# ucla-cdl/planet-lang architecture

> Architecture diagram of the GitHub repository ucla-cdl/planet-lang, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ucla-cdl/planet-lang
- Repository: https://github.com/ucla-cdl/planet-lang

## Overview

PLanet is a declarative tool for authoring and analyzing experimental designs. Researchers define variables and design constraints, optionally compose designs by nesting or crossing them, then the design’s Designer configures a solver to produce plans. The package also exposes unit assignment and analysis capabilities. The graph reflects documented features and relationships visible in the excerpts or SOURCE INDEX; unsampled implementation details are not expanded into speculative call paths.

Main entry points: [`src/planet/design.py`](https://github.com/ucla-cdl/planet-lang/blob/main/src/planet/design.py) (Design builder), [`src/planet/__init__.py`](https://github.com/ucla-cdl/planet-lang/blob/main/src/planet/__init__.py) (Public API), [`src/planet/nest.py`](https://github.com/ucla-cdl/planet-lang/blob/main/src/planet/nest.py) (Nested designs), [`src/planet/cross.py`](https://github.com/ucla-cdl/planet-lang/blob/main/src/planet/cross.py) (Crossed designs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Design authoring"]
  node_api["Public API<br/>[__init__.py]"]
  node_variables["Experiment variables<br/>[variable.py]"]
  node_design["Design builder<br/>[design.py]"]
  node_constraints["Design constraints<br/>[constraint.py]"]
  node_constraint_manager["Constraint manager"]
  node_nest["Nested designs<br/>[nest.py]"]
  node_cross["Crossed designs<br/>[cross.py]"]
end

subgraph group_generation["Plan generation"]
  node_designer["Design evaluation<br/>[designer.py]"]
  node_solver["Constraint solver<br/>[solver.py]"]
  node_bitvectors["Solver bitvectors<br/>[bitvector.py]"]
  node_plans["Plan generation<br/>[plans.py]"]
  node_randomizer["Plan randomization<br/>[randomizer.py]"]
end

subgraph group_assignment["Unit assignment"]
  node_units[("Units and groups<br/>[unit.py]")]
  node_assignment["Plan assignment<br/>[assignment.py]"]
end

subgraph group_analysis["Design analysis"]
  node_analysis["Effect analysis<br/>[analysis.py]"]
  node_formatter["Output formatting<br/>[formatter.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"authors designs"| node_api
node_api -->|"exposes"| node_design
node_api -->|"exposes"| node_variables
node_api -->|"exposes"| node_nest
node_api -->|"exposes"| node_cross
node_api -->|"exposes"| node_assignment
node_design -->|"adds variables"| node_variables
node_design -->|"creates manager"| node_constraint_manager
node_design -->|"adds constraints"| node_constraints
node_design -->|"starts evaluation"| node_designer
node_designer -->|"configures solver"| node_solver
node_solver -->|"creates bitvectors"| node_bitvectors
node_nest -->|"creates combined design"| node_design
node_cross -->|"creates combined design"| node_design
node_researcher -.->|"requests effect analysis"| node_analysis
node_researcher -.->|"defines participants"| node_units

click node_api "https://github.com/ucla-cdl/planet-lang/blob/main/src/planet/__init__.py"
click node_variables "https://github.com/ucla-cdl/planet-lang/blob/main/src/planet/variable.py"
click node_design "https://github.com/ucla-cdl/planet-lang/blob/main/src/planet/design.py"
click node_constraints "https://github.com/ucla-cdl/planet-lang/blob/main/src/planet/constraint.py"
click node_constraint_manager "https://github.com/ucla-cdl/planet-lang/blob/main/src/planet/constraint_manager.py"
click node_nest "https://github.com/ucla-cdl/planet-lang/blob/main/src/planet/nest.py"
click node_cross "https://github.com/ucla-cdl/planet-lang/blob/main/src/planet/cross.py"
click node_designer "https://github.com/ucla-cdl/planet-lang/blob/main/src/planet/designer.py"
click node_solver "https://github.com/ucla-cdl/planet-lang/blob/main/src/planet/solver.py"
click node_bitvectors "https://github.com/ucla-cdl/planet-lang/blob/main/src/planet/bitvector.py"
click node_plans "https://github.com/ucla-cdl/planet-lang/blob/main/src/planet/plans.py"
click node_randomizer "https://github.com/ucla-cdl/planet-lang/blob/main/src/planet/randomizer.py"
click node_units "https://github.com/ucla-cdl/planet-lang/blob/main/src/planet/unit.py"
click node_assignment "https://github.com/ucla-cdl/planet-lang/blob/main/src/planet/assignment.py"
click node_analysis "https://github.com/ucla-cdl/planet-lang/blob/main/src/planet/analysis.py"
click node_formatter "https://github.com/ucla-cdl/planet-lang/blob/main/src/planet/formatter.py"

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_api,node_variables,node_design,node_constraints,node_constraint_manager,node_nest,node_cross toneBlue
class node_designer,node_solver,node_bitvectors,node_plans,node_randomizer toneAmber
class node_units,node_assignment toneMint
class node_analysis,node_formatter toneRose
class node_researcher toneIndigo
```

## Components

### Design authoring

- [Public API](https://github.com/ucla-cdl/planet-lang/blob/main/src/planet/__init__.py): `src/planet/__init__.py`
- [Experiment variables](https://github.com/ucla-cdl/planet-lang/blob/main/src/planet/variable.py): `src/planet/variable.py`
- [Design builder](https://github.com/ucla-cdl/planet-lang/blob/main/src/planet/design.py): `src/planet/design.py`
- [Design constraints](https://github.com/ucla-cdl/planet-lang/blob/main/src/planet/constraint.py): `src/planet/constraint.py`
- [Constraint manager](https://github.com/ucla-cdl/planet-lang/blob/main/src/planet/constraint_manager.py): `src/planet/constraint_manager.py`
- [Nested designs](https://github.com/ucla-cdl/planet-lang/blob/main/src/planet/nest.py): `src/planet/nest.py`
- [Crossed designs](https://github.com/ucla-cdl/planet-lang/blob/main/src/planet/cross.py): `src/planet/cross.py`

### Plan generation

- [Design evaluation](https://github.com/ucla-cdl/planet-lang/blob/main/src/planet/designer.py): `src/planet/designer.py`
- [Constraint solver](https://github.com/ucla-cdl/planet-lang/blob/main/src/planet/solver.py): `src/planet/solver.py`
- [Solver bitvectors](https://github.com/ucla-cdl/planet-lang/blob/main/src/planet/bitvector.py): `src/planet/bitvector.py`
- [Plan generation](https://github.com/ucla-cdl/planet-lang/blob/main/src/planet/plans.py): `src/planet/plans.py`
- [Plan randomization](https://github.com/ucla-cdl/planet-lang/blob/main/src/planet/randomizer.py): `src/planet/randomizer.py`

### Unit assignment

- [Units and groups](https://github.com/ucla-cdl/planet-lang/blob/main/src/planet/unit.py): `src/planet/unit.py`
- [Plan assignment](https://github.com/ucla-cdl/planet-lang/blob/main/src/planet/assignment.py): `src/planet/assignment.py`

### Design analysis

- [Effect analysis](https://github.com/ucla-cdl/planet-lang/blob/main/src/planet/analysis.py): `src/planet/analysis.py`
- [Output formatting](https://github.com/ucla-cdl/planet-lang/blob/main/src/planet/formatter.py): `src/planet/formatter.py`

### Other components

- **Researcher**

## Connections

- Researcher → Public API: authors designs
- Public API → Design builder: exposes (evidence: `src/planet/__init__.py`)
- Public API → Experiment variables: exposes (evidence: `src/planet/__init__.py`)
- Public API → Nested designs: exposes (evidence: `src/planet/__init__.py`)
- Public API → Crossed designs: exposes (evidence: `src/planet/__init__.py`)
- Public API → Plan assignment: exposes (evidence: `src/planet/__init__.py`)
- Design builder → Experiment variables: adds variables (evidence: `src/planet/design.py`)
- Design builder → Constraint manager: creates manager (evidence: `src/planet/design.py`)
- Design builder → Design constraints: adds constraints (evidence: `src/planet/design.py`)
- Design builder → Design evaluation: starts evaluation (evidence: `src/planet/design.py`)
- Design evaluation → Constraint solver: configures solver (evidence: `src/planet/designer.py`)
- Constraint solver → Solver bitvectors: creates bitvectors (evidence: `src/planet/solver.py`)
- Nested designs → Design builder: creates combined design (evidence: `src/planet/nest.py`)
- Crossed designs → Design builder: creates combined design (evidence: `src/planet/cross.py`)
- Researcher → Effect analysis: requests effect analysis
- Researcher → Units and groups: defines participants (evidence: `src/planet/unit.py`)