# nxthingbutv0id/marscolonysimulation architecture

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

- Interactive diagram: https://gitdiagram.com/nxthingbutv0id/marscolonysimulation
- Repository: https://github.com/nxthingbutv0id/marscolonysimulation

## Overview

This Rust project simulates a Mars colony to study sustainability and how colonist role mixes affect outcomes. The principal workflow is to configure a scenario and population, run a tick-based simulation of colonists, tasks, machines, resources, and environmental events, then summarize results and write CSV output. The graph reflects the sampled implementation and SOURCE INDEX references; the README does not describe the command-line interface, so its initiating path is left unspecified.

Main entry points: [`src/model/colony/colony.rs`](https://github.com/nxthingbutv0id/marscolonysimulation/blob/master/src/model/colony/colony.rs) (Colony lifecycle), [`src/model/machines/machine.rs`](https://github.com/nxthingbutv0id/marscolonysimulation/blob/master/src/model/machines/machine.rs) (Machine operations), [`src/experiment/simulation.rs`](https://github.com/nxthingbutv0id/marscolonysimulation/blob/master/src/experiment/simulation.rs) (Simulation runner), [`src/model/colony/resources.rs`](https://github.com/nxthingbutv0id/marscolonysimulation/blob/master/src/model/colony/resources.rs) (Resource pools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experiments["Experiments"]
  node_main["Program entry<br/>[main.rs]"]
  node_scenario["Scenario setup<br/>[scenario.rs]"]
  node_population["Role populations<br/>[population.rs]"]
  node_simulator["Simulation runner<br/>[simulation.rs]"]
  node_random["Random generator<br/>[random.rs]"]
  node_results["Run results<br/>[run_results.rs]"]
  node_csv["CSV output<br/>[csv_writer.rs]"]
end

subgraph group_colony["Colony Simulation"]
  node_colony_core["Colony lifecycle<br/>[colony.rs]"]
end

subgraph group_agents["Agents and Tasks"]
  node_colonists["Colonist decisions<br/>[colonists.rs]"]
  node_tasks["Colony tasks<br/>[tasks.rs]"]
end

subgraph group_operations["Environment and Machines"]
  node_environment["Environmental events<br/>[environment.rs]"]
  node_machines["Machine operations<br/>[machine.rs]"]
  node_greenhouse["Greenhouse<br/>[greenhouse.rs]"]
  node_solar["Solar array<br/>[solar_array.rs]"]
  node_probability["Failure distributions<br/>[probability.rs]"]
end

subgraph group_state["State and Time"]
  node_resources[("Resource pools<br/>[resources.rs]")]
  node_time["Simulation clock<br/>[time.rs]"]
end

node_scenario -->|"builds roles"| node_population
node_population -->|"uses randomness"| node_random
node_scenario -->|"configures resources"| node_resources
node_simulator -->|"accepts scenario"| node_scenario
node_simulator -->|"advances colony"| node_colony_core
node_simulator -->|"updates events"| node_environment
node_simulator -->|"seeds randomness"| node_random
node_simulator -->|"advances clock"| node_time
node_simulator -->|"produces summary"| node_results
node_csv -->|"writes results"| node_results
node_csv -->|"reads resource totals"| node_resources
node_colony_core -->|"collects actions"| node_colonists
node_colony_core -->|"manages tasks"| node_tasks
node_colony_core -->|"checks conditions"| node_environment
node_colony_core -->|"runs machines"| node_machines
node_colony_core -->|"updates stores"| node_resources
node_colony_core -->|"uses simulation time"| node_time
node_colonists -->|"selects task work"| node_tasks
node_colonists -->|"selects machine work"| node_machines
node_machines -->|"computes resource flow"| node_resources
node_machines -->|"uses conditions"| node_environment
node_machines -->|"checks failures"| node_probability
node_greenhouse -->|"uses resource pool"| node_resources
node_greenhouse -->|"uses conditions"| node_environment
node_greenhouse -->|"implements machine"| node_machines
node_solar -->|"produces electricity"| node_resources
node_solar -->|"applies storm effect"| node_environment
node_solar -->|"implements machine"| node_machines
node_probability -->|"samples distributions"| node_random

click node_main "https://github.com/nxthingbutv0id/marscolonysimulation/blob/master/src/main.rs"
click node_scenario "https://github.com/nxthingbutv0id/marscolonysimulation/blob/master/src/experiment/scenario.rs"
click node_population "https://github.com/nxthingbutv0id/marscolonysimulation/blob/master/src/experiment/population.rs"
click node_simulator "https://github.com/nxthingbutv0id/marscolonysimulation/blob/master/src/experiment/simulation.rs"
click node_random "https://github.com/nxthingbutv0id/marscolonysimulation/blob/master/src/experiment/random.rs"
click node_results "https://github.com/nxthingbutv0id/marscolonysimulation/blob/master/src/experiment/run_results.rs"
click node_csv "https://github.com/nxthingbutv0id/marscolonysimulation/blob/master/src/experiment/csv_writer.rs"
click node_colony_core "https://github.com/nxthingbutv0id/marscolonysimulation/blob/master/src/model/colony/colony.rs"
click node_colonists "https://github.com/nxthingbutv0id/marscolonysimulation/blob/master/src/model/agent/colonists.rs"
click node_tasks "https://github.com/nxthingbutv0id/marscolonysimulation/blob/master/src/model/colony/tasks.rs"
click node_environment "https://github.com/nxthingbutv0id/marscolonysimulation/blob/master/src/model/colony/environment.rs"
click node_machines "https://github.com/nxthingbutv0id/marscolonysimulation/blob/master/src/model/machines/machine.rs"
click node_greenhouse "https://github.com/nxthingbutv0id/marscolonysimulation/blob/master/src/model/machines/greenhouse.rs"
click node_solar "https://github.com/nxthingbutv0id/marscolonysimulation/blob/master/src/model/machines/solar_array.rs"
click node_probability "https://github.com/nxthingbutv0id/marscolonysimulation/blob/master/src/model/machines/probability.rs"
click node_resources "https://github.com/nxthingbutv0id/marscolonysimulation/blob/master/src/model/colony/resources.rs"
click node_time "https://github.com/nxthingbutv0id/marscolonysimulation/blob/master/src/model/time.rs"

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_main,node_scenario,node_population,node_simulator,node_random,node_results,node_csv toneBlue
class node_colony_core toneAmber
class node_colonists,node_tasks toneMint
class node_environment,node_machines,node_greenhouse,node_solar,node_probability toneRose
class node_resources,node_time toneIndigo
```

## Components

### Experiments

- [Program entry](https://github.com/nxthingbutv0id/marscolonysimulation/blob/master/src/main.rs): `src/main.rs`
- [Scenario setup](https://github.com/nxthingbutv0id/marscolonysimulation/blob/master/src/experiment/scenario.rs): `src/experiment/scenario.rs`
- [Role populations](https://github.com/nxthingbutv0id/marscolonysimulation/blob/master/src/experiment/population.rs): `src/experiment/population.rs`
- [Simulation runner](https://github.com/nxthingbutv0id/marscolonysimulation/blob/master/src/experiment/simulation.rs): `src/experiment/simulation.rs`
- [Random generator](https://github.com/nxthingbutv0id/marscolonysimulation/blob/master/src/experiment/random.rs): `src/experiment/random.rs`
- [Run results](https://github.com/nxthingbutv0id/marscolonysimulation/blob/master/src/experiment/run_results.rs): `src/experiment/run_results.rs`
- [CSV output](https://github.com/nxthingbutv0id/marscolonysimulation/blob/master/src/experiment/csv_writer.rs): `src/experiment/csv_writer.rs`

### Colony Simulation

- [Colony lifecycle](https://github.com/nxthingbutv0id/marscolonysimulation/blob/master/src/model/colony/colony.rs): `src/model/colony/colony.rs`

### Agents and Tasks

- [Colonist decisions](https://github.com/nxthingbutv0id/marscolonysimulation/blob/master/src/model/agent/colonists.rs): `src/model/agent/colonists.rs`
- [Colony tasks](https://github.com/nxthingbutv0id/marscolonysimulation/blob/master/src/model/colony/tasks.rs): `src/model/colony/tasks.rs`

### Environment and Machines

- [Environmental events](https://github.com/nxthingbutv0id/marscolonysimulation/blob/master/src/model/colony/environment.rs): `src/model/colony/environment.rs`
- [Machine operations](https://github.com/nxthingbutv0id/marscolonysimulation/blob/master/src/model/machines/machine.rs): `src/model/machines/machine.rs`
- [Greenhouse](https://github.com/nxthingbutv0id/marscolonysimulation/blob/master/src/model/machines/greenhouse.rs): `src/model/machines/greenhouse.rs`
- [Solar array](https://github.com/nxthingbutv0id/marscolonysimulation/blob/master/src/model/machines/solar_array.rs): `src/model/machines/solar_array.rs`
- [Failure distributions](https://github.com/nxthingbutv0id/marscolonysimulation/blob/master/src/model/machines/probability.rs): `src/model/machines/probability.rs`

### State and Time

- [Resource pools](https://github.com/nxthingbutv0id/marscolonysimulation/blob/master/src/model/colony/resources.rs): `src/model/colony/resources.rs`
- [Simulation clock](https://github.com/nxthingbutv0id/marscolonysimulation/blob/master/src/model/time.rs): `src/model/time.rs`

## Connections

- Scenario setup → Role populations: builds roles (evidence: `src/experiment/scenario.rs`)
- Role populations → Random generator: uses randomness (evidence: `src/experiment/population.rs`)
- Scenario setup → Resource pools: configures resources (evidence: `src/experiment/scenario.rs`)
- Simulation runner → Scenario setup: accepts scenario (evidence: `src/experiment/simulation.rs`)
- Simulation runner → Colony lifecycle: advances colony (evidence: `src/experiment/simulation.rs`)
- Simulation runner → Environmental events: updates events (evidence: `src/experiment/simulation.rs`)
- Simulation runner → Random generator: seeds randomness (evidence: `src/experiment/simulation.rs`)
- Simulation runner → Simulation clock: advances clock (evidence: `src/experiment/simulation.rs`)
- Simulation runner → Run results: produces summary (evidence: `src/experiment/simulation.rs`)
- CSV output → Run results: writes results (evidence: `src/experiment/csv_writer.rs`)
- CSV output → Resource pools: reads resource totals (evidence: `src/experiment/csv_writer.rs`)
- Colony lifecycle → Colonist decisions: collects actions (evidence: `src/model/colony/colony.rs`)
- Colony lifecycle → Colony tasks: manages tasks (evidence: `src/model/colony/colony.rs`)
- Colony lifecycle → Environmental events: checks conditions (evidence: `src/model/colony/colony.rs`)
- Colony lifecycle → Machine operations: runs machines (evidence: `src/model/colony/colony.rs`)
- Colony lifecycle → Resource pools: updates stores (evidence: `src/model/colony/colony.rs`)
- Colony lifecycle → Simulation clock: uses simulation time (evidence: `src/model/colony/colony.rs`)
- Colonist decisions → Colony tasks: selects task work (evidence: `src/model/agent/colonists.rs`)
- Colonist decisions → Machine operations: selects machine work (evidence: `src/model/agent/colonists.rs`)
- Machine operations → Resource pools: computes resource flow (evidence: `src/model/machines/machine.rs`)
- Machine operations → Environmental events: uses conditions (evidence: `src/model/machines/machine.rs`)
- Machine operations → Failure distributions: checks failures (evidence: `src/model/machines/machine.rs`)
- Greenhouse → Resource pools: uses resource pool (evidence: `src/model/machines/greenhouse.rs`)
- Greenhouse → Environmental events: uses conditions (evidence: `src/model/machines/greenhouse.rs`)
- Greenhouse → Machine operations: implements machine (evidence: `src/model/machines/greenhouse.rs`)
- Solar array → Resource pools: produces electricity (evidence: `src/model/machines/solar_array.rs`)
- Solar array → Environmental events: applies storm effect (evidence: `src/model/machines/solar_array.rs`)
- Solar array → Machine operations: implements machine (evidence: `src/model/machines/solar_array.rs`)
- Failure distributions → Random generator: samples distributions (evidence: `src/model/machines/probability.rs`)
