# warmjademe/plc_generation_empirical_study architecture

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

- Interactive diagram: https://gitdiagram.com/warmjademe/plc_generation_empirical_study
- Repository: https://github.com/warmjademe/plc_generation_empirical_study

## Overview

This repository is a research artifact for evaluating bounded generation of IEC 61131-3 Structured Text, centered on a benchmark and the Evidence-Guided Bounded Synthesis (EGBS) harness. Its principal workflow loads a public requirement and fixed interface, generates bounded candidates, validates them, and records evidence; the full correctness chain includes compilation, formal checks, and runtime tests. It also contains benchmark construction and qualification, comparison methods, and a deployment service. The graph uses documented relationships and indexed imports; unsampled deployment details are represented only where the index supports them.

Main entry points: [`our_method/src/plc_loop/orchestrator.py`](https://github.com/warmjademe/plc_generation_empirical_study/blob/main/our_method/src/plc_loop/orchestrator.py) (Bounded synthesis), [`our_method/src/plc_loop/validators.py`](https://github.com/warmjademe/plc_generation_empirical_study/blob/main/our_method/src/plc_loop/validators.py) (Validator adapters), [`our_method/src/plc_loop/cli.py`](https://github.com/warmjademe/plc_generation_empirical_study/blob/main/our_method/src/plc_loop/cli.py) (Harness CLI), [`our_method_Deploy/src/plc_deploy/pipeline.py`](https://github.com/warmjademe/plc_generation_empirical_study/blob/main/our_method_Deploy/src/plc_deploy/pipeline.py) (Job pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_benchmark["Benchmark"]
  node_task_bank["Task bank<br/>[build_dataset.py]"]
  node_task_design["Task design<br/>[challenge_tasks.py]"]
  node_benchmark_audit["Benchmark audit<br/>[audit_dataset.py]"]
end

subgraph group_harness["EGBS harness"]
  node_harness_cli["Harness CLI<br/>[cli.py]"]
  node_task_loader["Task loader<br/>[dataset.py]"]
  node_bounded_loop["Bounded synthesis<br/>[orchestrator.py]"]
  node_model_client["Model client<br/>[client.py]"]
  node_context_builder["Context builder<br/>[context.py]"]
  node_candidate_policy["Candidate policy<br/>[policy.py]"]
  node_evidence_ledger["Evidence ledger<br/>[ledger.py]"]
  node_validator_chain["Validator adapters<br/>[validators.py]"]
end

subgraph group_deployment["Deployment service"]
  node_api["Web API<br/>[main.py]"]
  node_job_pipeline["Job pipeline<br/>[pipeline.py]"]
  node_job_store[("Job store<br/>[store.py]")]
end

subgraph group_study["Study comparisons"]
  node_comparison_adapters["External baselines"]
  node_ablation_runs["Internal ablations"]
  node_experiment_launchers["Experiment launchers"]
end

node_researcher(("Researcher"))
node_matiec["MatIEC compiler"]
node_plcverif["PLCverif"]
node_openplc["OpenPLC runtime"]

node_researcher -->|"runs"| node_harness_cli
node_task_design -->|"supplies tasks"| node_task_bank
node_researcher -->|"audits"| node_benchmark_audit
node_harness_cli -.->|"loads task"| node_task_loader
node_harness_cli -.->|"starts run"| node_bounded_loop
node_bounded_loop -->|"uses contract"| node_task_loader
node_bounded_loop -->|"requests candidates"| node_model_client
node_bounded_loop -->|"builds context"| node_context_builder
node_bounded_loop -->|"selects anchor"| node_candidate_policy
node_bounded_loop -->|"records evidence"| node_evidence_ledger
node_bounded_loop -->|"validates candidates"| node_validator_chain
node_validator_chain -->|"reads test suites"| node_task_loader
node_validator_chain -->|"compiles with"| node_matiec
node_validator_chain -->|"checks properties"| node_plcverif
node_validator_chain -->|"runs scan tests"| node_openplc
node_api -->|"dispatches jobs"| node_job_pipeline
node_api -->|"manages jobs"| node_job_store
node_job_pipeline -->|"reads job state"| node_job_store
node_job_pipeline -->|"runs synthesis"| node_bounded_loop
node_researcher -->|"runs comparison"| node_comparison_adapters
node_researcher -->|"runs controls"| node_ablation_runs
node_experiment_launchers -.->|"launches experiments"| node_comparison_adapters

click node_task_bank "https://github.com/warmjademe/plc_generation_empirical_study/blob/main/datasets_100/build_dataset.py"
click node_task_design "https://github.com/warmjademe/plc_generation_empirical_study/blob/main/datasets/tools/challenge_tasks.py"
click node_benchmark_audit "https://github.com/warmjademe/plc_generation_empirical_study/blob/main/datasets_100/audit_dataset.py"
click node_harness_cli "https://github.com/warmjademe/plc_generation_empirical_study/blob/main/our_method/src/plc_loop/cli.py"
click node_task_loader "https://github.com/warmjademe/plc_generation_empirical_study/blob/main/our_method/src/plc_loop/dataset.py"
click node_bounded_loop "https://github.com/warmjademe/plc_generation_empirical_study/blob/main/our_method/src/plc_loop/orchestrator.py"
click node_model_client "https://github.com/warmjademe/plc_generation_empirical_study/blob/main/our_method/src/plc_loop/client.py"
click node_context_builder "https://github.com/warmjademe/plc_generation_empirical_study/blob/main/our_method/src/plc_loop/context.py"
click node_candidate_policy "https://github.com/warmjademe/plc_generation_empirical_study/blob/main/our_method/src/plc_loop/policy.py"
click node_evidence_ledger "https://github.com/warmjademe/plc_generation_empirical_study/blob/main/our_method/src/plc_loop/ledger.py"
click node_validator_chain "https://github.com/warmjademe/plc_generation_empirical_study/blob/main/our_method/src/plc_loop/validators.py"
click node_api "https://github.com/warmjademe/plc_generation_empirical_study/blob/main/our_method_Deploy/src/plc_deploy/main.py"
click node_job_pipeline "https://github.com/warmjademe/plc_generation_empirical_study/blob/main/our_method_Deploy/src/plc_deploy/pipeline.py"
click node_job_store "https://github.com/warmjademe/plc_generation_empirical_study/blob/main/our_method_Deploy/src/plc_deploy/store.py"
click node_comparison_adapters "https://github.com/warmjademe/plc_generation_empirical_study/blob/main/baseline0_external_runner.py"
click node_ablation_runs "https://github.com/warmjademe/plc_generation_empirical_study/blob/main/ablation0_runner.py"
click node_experiment_launchers "https://github.com/warmjademe/plc_generation_empirical_study/blob/main/orchestrate_datasets100_experiments.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_task_bank,node_task_design,node_benchmark_audit toneBlue
class node_harness_cli,node_task_loader,node_bounded_loop,node_model_client,node_context_builder,node_candidate_policy,node_evidence_ledger,node_validator_chain toneAmber
class node_api,node_job_pipeline,node_job_store toneMint
class node_comparison_adapters,node_ablation_runs,node_experiment_launchers toneRose
class node_researcher,node_matiec,node_plcverif,node_openplc toneIndigo
```

## Components

### Benchmark

- [Task bank](https://github.com/warmjademe/plc_generation_empirical_study/blob/main/datasets_100/build_dataset.py): `datasets_100/build_dataset.py`
- [Task design](https://github.com/warmjademe/plc_generation_empirical_study/blob/main/datasets/tools/challenge_tasks.py): `datasets/tools/challenge_tasks.py`
- [Benchmark audit](https://github.com/warmjademe/plc_generation_empirical_study/blob/main/datasets_100/audit_dataset.py): `datasets_100/audit_dataset.py`

### EGBS harness

- [Harness CLI](https://github.com/warmjademe/plc_generation_empirical_study/blob/main/our_method/src/plc_loop/cli.py): `our_method/src/plc_loop/cli.py`
- [Task loader](https://github.com/warmjademe/plc_generation_empirical_study/blob/main/our_method/src/plc_loop/dataset.py): `our_method/src/plc_loop/dataset.py`
- [Bounded synthesis](https://github.com/warmjademe/plc_generation_empirical_study/blob/main/our_method/src/plc_loop/orchestrator.py): `our_method/src/plc_loop/orchestrator.py`
- [Model client](https://github.com/warmjademe/plc_generation_empirical_study/blob/main/our_method/src/plc_loop/client.py): `our_method/src/plc_loop/client.py`
- [Context builder](https://github.com/warmjademe/plc_generation_empirical_study/blob/main/our_method/src/plc_loop/context.py): `our_method/src/plc_loop/context.py`
- [Candidate policy](https://github.com/warmjademe/plc_generation_empirical_study/blob/main/our_method/src/plc_loop/policy.py): `our_method/src/plc_loop/policy.py`
- [Evidence ledger](https://github.com/warmjademe/plc_generation_empirical_study/blob/main/our_method/src/plc_loop/ledger.py): `our_method/src/plc_loop/ledger.py`
- [Validator adapters](https://github.com/warmjademe/plc_generation_empirical_study/blob/main/our_method/src/plc_loop/validators.py): `our_method/src/plc_loop/validators.py`

### Deployment service

- [Web API](https://github.com/warmjademe/plc_generation_empirical_study/blob/main/our_method_Deploy/src/plc_deploy/main.py): `our_method_Deploy/src/plc_deploy/main.py`
- [Job pipeline](https://github.com/warmjademe/plc_generation_empirical_study/blob/main/our_method_Deploy/src/plc_deploy/pipeline.py): `our_method_Deploy/src/plc_deploy/pipeline.py`
- [Job store](https://github.com/warmjademe/plc_generation_empirical_study/blob/main/our_method_Deploy/src/plc_deploy/store.py): `our_method_Deploy/src/plc_deploy/store.py`

### Study comparisons

- [External baselines](https://github.com/warmjademe/plc_generation_empirical_study/blob/main/baseline0_external_runner.py): `baseline0_external_runner.py`
- [Internal ablations](https://github.com/warmjademe/plc_generation_empirical_study/blob/main/ablation0_runner.py): `ablation0_runner.py`
- [Experiment launchers](https://github.com/warmjademe/plc_generation_empirical_study/blob/main/orchestrate_datasets100_experiments.py): `orchestrate_datasets100_experiments.py`

### Other components

- **Researcher**
- **MatIEC compiler**
- **PLCverif**
- **OpenPLC runtime**

## Connections

- Researcher → Harness CLI: runs (evidence: `README.md`)
- Task design → Task bank: supplies tasks
- Researcher → Benchmark audit: audits (evidence: `README.md`)
- Harness CLI → Task loader: loads task
- Harness CLI → Bounded synthesis: starts run
- Bounded synthesis → Task loader: uses contract (evidence: `our_method/src/plc_loop/orchestrator.py`)
- Bounded synthesis → Model client: requests candidates (evidence: `our_method/src/plc_loop/orchestrator.py`)
- Bounded synthesis → Context builder: builds context (evidence: `our_method/src/plc_loop/orchestrator.py`)
- Bounded synthesis → Candidate policy: selects anchor (evidence: `our_method/src/plc_loop/orchestrator.py`)
- Bounded synthesis → Evidence ledger: records evidence (evidence: `our_method/src/plc_loop/orchestrator.py`)
- Bounded synthesis → Validator adapters: validates candidates (evidence: `our_method/src/plc_loop/orchestrator.py`)
- Validator adapters → Task loader: reads test suites (evidence: `our_method/src/plc_loop/validators.py`)
- Validator adapters → MatIEC compiler: compiles with (evidence: `README.md`)
- Validator adapters → PLCverif: checks properties (evidence: `README.md`)
- Validator adapters → OpenPLC runtime: runs scan tests (evidence: `README.md`)
- Web API → Job pipeline: dispatches jobs (evidence: `our_method_Deploy/src/plc_deploy/main.py`)
- Web API → Job store: manages jobs (evidence: `our_method_Deploy/src/plc_deploy/main.py`)
- Job pipeline → Job store: reads job state (evidence: `our_method_Deploy/src/plc_deploy/pipeline.py`)
- Job pipeline → Bounded synthesis: runs synthesis (evidence: `our_method_Deploy/src/plc_deploy/pipeline.py`)
- Researcher → External baselines: runs comparison (evidence: `README.md`)
- Researcher → Internal ablations: runs controls (evidence: `README.md`)
- Experiment launchers → External baselines: launches experiments
