# hnu-bigherox/robocup_changsha architecture

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

- Interactive diagram: https://gitdiagram.com/hnu-bigherox/robocup_changsha
- Repository: https://github.com/hnu-bigherox/robocup_changsha

## Overview

Coverage Bench is a multi-robot moving-target coverage benchmark and competition evaluation framework. The principal workflow is to validate a participant submission, load an evaluation suite (optionally governed by a release bundle), run the policy against seeded scenarios, then aggregate episode results into metrics and a performance score. The environment stages scenario creation, robot and target motion, observations, rewards, and metrics. The repository also provides submission auditing, release management, result comparison, and archiving. Some orchestration links follow module responsibilities and README behavior; unsampled implementation details are not asserted.

Main entry points: [`coverage_bench/evaluation.py`](https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/evaluation.py) (Evaluation orchestration), [`coverage_bench/envs/parallel_env.py`](https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/envs/parallel_env.py) (Parallel task environment), [`coverage_bench/cli.py`](https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/cli.py) (CLI commands), [`coverage_bench/host_runner.py`](https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/host_runner.py) (Host runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Evaluation entrypoints"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_submission["Submission validation<br/>[submission.py]"]
  node_release["Release bundle<br/>[release.py]"]
end

subgraph group_environment["Task environment"]
  node_environment["Parallel task environment<br/>[parallel_env.py]"]
  node_scenario["Scenario generation<br/>[scenario.py]"]
  node_physics["Robot dynamics<br/>[physics.py]"]
  node_motion["Target motion<br/>[motion.py]"]
  node_observations["Observation encoding<br/>[observations.py]"]
  node_rewards["Reward calculation<br/>[rewards.py]"]
  node_metrics["Episode metrics<br/>[metrics.py]"]
end

subgraph group_policy["Policy protocol"]
  node_runtime["Policy runtime<br/>[runtime.py]"]
  node_protocol["Observation/action protocol<br/>[protocol.py]"]
  node_participant_policy["Template policy<br/>[entry.py]"]
  node_training["PPO training example<br/>[train.py]"]
end

subgraph group_evaluation["Evaluation and results"]
  node_suite["Evaluation suites<br/>[suites.py]"]
  node_evaluation["Evaluation orchestration<br/>[evaluation.py]"]
  node_host["Host runner<br/>[host_runner.py]"]
  node_scoring["Score aggregation<br/>[scoring.py]"]
  node_results["Evaluation results<br/>[results.py]"]
  node_audit["Evaluation audit<br/>[audit.py]"]
  node_comparison["Result comparison<br/>[comparison.py]"]
  node_archive["Result archive<br/>[archive.py]"]
end

node_participant(("Participant"))

node_participant -->|"submits policy"| node_cli
node_cli -->|"validates submission"| node_submission
node_cli -.->|"loads optional bundle"| node_release
node_cli -->|"loads suite"| node_suite
node_cli -->|"starts evaluation"| node_evaluation
node_evaluation -->|"uses validated policy"| node_submission
node_evaluation -->|"uses cases"| node_suite
node_evaluation -->|"runs episodes"| node_host
node_host -->|"dispatches policy calls"| node_runtime
node_runtime -->|"invokes entrypoint"| node_participant_policy
node_participant_policy -->|"flattens observations"| node_protocol
node_training -.->|"trains through"| node_environment
node_training -->|"shares flattening"| node_protocol
node_host -->|"steps environment"| node_environment
node_environment -->|"initializes scenario"| node_scenario
node_environment -->|"advances robots"| node_physics
node_environment -->|"advances targets"| node_motion
node_environment -->|"encodes observations"| node_observations
node_environment -->|"computes rewards"| node_rewards
node_environment -->|"computes step metrics"| node_metrics
node_evaluation -->|"aggregates episodes"| node_metrics
node_evaluation -->|"calculates score"| node_scoring
node_evaluation -->|"writes results"| node_results
node_evaluation -->|"records audit"| node_audit
node_comparison -->|"compares results"| node_results
node_archive -->|"archives results"| node_results

click node_cli "https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/cli.py"
click node_submission "https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/submission.py"
click node_release "https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/release.py"
click node_suite "https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/suites.py"
click node_evaluation "https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/evaluation.py"
click node_host "https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/host_runner.py"
click node_runtime "https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/runtime.py"
click node_protocol "https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/protocol.py"
click node_participant_policy "https://github.com/hnu-bigherox/robocup_changsha/blob/master/participant/_template/entry.py"
click node_training "https://github.com/hnu-bigherox/robocup_changsha/blob/master/participant/_template/train.py"
click node_environment "https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/envs/parallel_env.py"
click node_scenario "https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/envs/scenario.py"
click node_physics "https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/envs/physics.py"
click node_motion "https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/envs/motion.py"
click node_observations "https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/observations.py"
click node_rewards "https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/rewards.py"
click node_metrics "https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/metrics.py"
click node_scoring "https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/scoring.py"
click node_results "https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/results.py"
click node_audit "https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/audit.py"
click node_comparison "https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/comparison.py"
click node_archive "https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/archive.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_cli,node_submission,node_release toneBlue
class node_environment,node_scenario,node_physics,node_motion,node_observations,node_rewards,node_metrics toneAmber
class node_runtime,node_protocol,node_participant_policy,node_training toneMint
class node_suite,node_evaluation,node_host,node_scoring,node_results,node_audit,node_comparison,node_archive toneRose
class node_participant toneIndigo
```

## Components

### Evaluation entrypoints

- [CLI commands](https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/cli.py): `coverage_bench/cli.py`
- [Submission validation](https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/submission.py): `coverage_bench/submission.py`
- [Release bundle](https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/release.py): `coverage_bench/release.py`

### Task environment

- [Parallel task environment](https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/envs/parallel_env.py): `coverage_bench/envs/parallel_env.py`
- [Scenario generation](https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/envs/scenario.py): `coverage_bench/envs/scenario.py`
- [Robot dynamics](https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/envs/physics.py): `coverage_bench/envs/physics.py`
- [Target motion](https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/envs/motion.py): `coverage_bench/envs/motion.py`
- [Observation encoding](https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/observations.py): `coverage_bench/observations.py`
- [Reward calculation](https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/rewards.py): `coverage_bench/rewards.py`
- [Episode metrics](https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/metrics.py): `coverage_bench/metrics.py`

### Policy protocol

- [Policy runtime](https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/runtime.py): `coverage_bench/runtime.py`
- [Observation/action protocol](https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/protocol.py): `coverage_bench/protocol.py`
- [Template policy](https://github.com/hnu-bigherox/robocup_changsha/blob/master/participant/_template/entry.py): `participant/_template/entry.py`
- [PPO training example](https://github.com/hnu-bigherox/robocup_changsha/blob/master/participant/_template/train.py): `participant/_template/train.py`

### Evaluation and results

- [Evaluation suites](https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/suites.py): `coverage_bench/suites.py`
- [Evaluation orchestration](https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/evaluation.py): `coverage_bench/evaluation.py`
- [Host runner](https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/host_runner.py): `coverage_bench/host_runner.py`
- [Score aggregation](https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/scoring.py): `coverage_bench/scoring.py`
- [Evaluation results](https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/results.py): `coverage_bench/results.py`
- [Evaluation audit](https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/audit.py): `coverage_bench/audit.py`
- [Result comparison](https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/comparison.py): `coverage_bench/comparison.py`
- [Result archive](https://github.com/hnu-bigherox/robocup_changsha/blob/master/coverage_bench/archive.py): `coverage_bench/archive.py`

### Other components

- **Participant**

## Connections

- Participant → CLI commands: submits policy
- CLI commands → Submission validation: validates submission
- CLI commands → Release bundle: loads optional bundle
- CLI commands → Evaluation suites: loads suite
- CLI commands → Evaluation orchestration: starts evaluation
- Evaluation orchestration → Submission validation: uses validated policy
- Evaluation orchestration → Evaluation suites: uses cases
- Evaluation orchestration → Host runner: runs episodes
- Host runner → Policy runtime: dispatches policy calls
- Policy runtime → Template policy: invokes entrypoint
- Template policy → Observation/action protocol: flattens observations
- PPO training example → Parallel task environment: trains through
- PPO training example → Observation/action protocol: shares flattening
- Host runner → Parallel task environment: steps environment
- Parallel task environment → Scenario generation: initializes scenario
- Parallel task environment → Robot dynamics: advances robots
- Parallel task environment → Target motion: advances targets
- Parallel task environment → Observation encoding: encodes observations
- Parallel task environment → Reward calculation: computes rewards
- Parallel task environment → Episode metrics: computes step metrics
- Evaluation orchestration → Episode metrics: aggregates episodes
- Evaluation orchestration → Score aggregation: calculates score
- Evaluation orchestration → Evaluation results: writes results
- Evaluation orchestration → Evaluation audit: records audit
- Result comparison → Evaluation results: compares results
- Result archive → Evaluation results: archives results