# lamalab-org/photocat-hte architecture

> Architecture diagram of the GitHub repository lamalab-org/photocat-hte, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lamalab-org/photocat-hte
- Repository: https://github.com/lamalab-org/photocat-hte

## Overview

##### Project type and purpose
- This is a single‐language (Python) orchestration tool for running high-throughput photocatalysis experiments (HTE) using a Chemspeed AutoSuite, programmable power supply, and FireSting sensor. It also contains a data‐analysis pipeline for processing experimental results.

##### File structure
- Top-level directories:
- config – YAML definitions (experiments.yml, setup.yml, etc.)
- experiments – entrypoint “run.py” that kicks off the experiment loop
- src/photolooper – core library: hardware interfaces and experiment logic
- data – raw .app blobs captured from AutoSuite runs
- data_analysis – scripts and folders to parse raw data into CSV/JSON and generate visualizations
- Key files:
- setup.py – package installer
- src/photolooper/main.py – CLI entrypoint for the photolooper tool
- data_analysis/*.py – analysis pipelines
- External interfaces: Chemspeed AutoSuite program (reads/writes CSV), FireSting pH sensor, programmable power supply.

##### README for additional insights
- The flow:
a. Load setup.yml and experiments.yml
b. Configure hardware (ports, folders)
c. Launch AutoSuite program (external)
d. Run “python run.py” → Python code monitors/writes values_for_experiment.csv, loops based on “run” flag
e. Collects .app experiment output into data/
f. Separate data_analysis scripts parse those .app files into CSV/JSON and produce visualizations.

- Configuration Loader (YAML)
- Experiment Orchestrator (experiments/run.py + photolooper.main)
- Hardware Abstraction Layer (photolooper.firesting, .powersupply)
- AutoSuite External Controller (Chemspeed)
- File System Storage (raw .app files in data/, config files)
- Data Analysis Pipeline (data_analysis/*.py → CSV/JSON → plots)
1. Configuration Loader → Experiment Orchestrator
2. Experiment Orchestrator → Hardware Abstraction → Power Supply & FireSting Sensor
3. Experiment Orchestrator ↔ AutoSuite (via values_for_experiment.csv and .app files)
4. Raw .app files written to data/
5. Data Analysis Pipeline reads data/, writes processed CSV/JSON, then Visualizations
c. Architectural patterns / design principles:
- Modularization: separate packages for CLI, hardware drivers, experiment logic, and analysis
- File-based messaging: coordination with AutoSuite via a shared CSV file
- Config-first design: all runtime parameters come from YAML
d. Relevant technologies:
- Python 3, PyYAML (for config), pandas (in data_analysis, presumed), matplotlib/PDF for plots
- Chemspeed AutoSuite (external Windows program)
- FireSting pH sensor, programmable power supply (via serial ports)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Configuration (YAML)"
        ExperimentsYML[(experiments.yml)]:::storage
        SetupYML[(setup.yml)]:::storage
        ExperimentYML[(experiment.yml)]:::storage
    end

    subgraph "CLI & Orchestrator"
        MainPY["Photolooper CLI\n(main.py)"]:::pythonModule
        RunPY["Experiment Orchestrator\n(run.py)"]:::pythonModule
    end

    subgraph "Hardware Abstraction Layer"
        FirestingDriver["FireSting Driver\n(firesting.py)"]:::pythonModule
        PowersupplyDriver["Power Supply Driver\n(powersupply.py)"]:::pythonModule
        Status["Status & Utils\n(status.py)"]:::pythonModule
        Utils["Utilities\n(utils.py)"]:::pythonModule
        RXN_ODE["Reaction ODE Fitting\n(rxn_ode_fitting.py)"]:::pythonModule
        Fit["Fitting Logic\n(fit.py)"]:::pythonModule
    end

    subgraph "External Systems"
        AutoSuite["Chemspeed AutoSuite"]:::external
        FireStingSensor["FireSting Sensor"]:::external
        PowerSupplyHW["Programmable Power Supply"]:::external
    end

    subgraph "Data Analysis Pipeline"
        DataFit["Data Fit Analysis\n(data_fit_analysis.py)"]:::pythonModule
        RateAnalysis["Rate Analysis\n(rate_analysis.py)"]:::pythonModule
    end

    ExperimentsYML -->|load| MainPY
    SetupYML -->|load| MainPY
    ExperimentYML -->|load| MainPY
    MainPY -->|launches| RunPY

    RunPY -->|calls| FirestingDriver
    RunPY -->|calls| PowersupplyDriver
    RunPY -->|uses| Status
    RunPY -->|uses| Utils
    RunPY -->|executes| RXN_ODE
    RunPY -->|executes| Fit

    FirestingDriver -->|reads/writes| FireStingSensor
    PowersupplyDriver -->|controls| PowerSupplyHW

    RunPY -->|writes| MessagingCSV[(values_for_experiment.csv)]:::storage
    MessagingCSV -->|read by| AutoSuite
    AutoSuite -->|produces| RawData[(Raw .app Files)]:::storage

    RawData -->|parsed by| DataFit
    RawData -->|parsed by| RateAnalysis
    DataFit -->|writes| ProcessedCSVStorage[(Processed CSVs)]:::storage
    RateAnalysis -->|writes| ProcessedJSONStorage[(Processed JSONs)]:::storage
    DataFit -->|generates| Visualizations[(Visualizations PDFs)]:::storage
    RateAnalysis -->|generates| Visualizations

    classDef pythonModule fill:#ADD8E6,stroke:#000
    classDef external fill:#90EE90,stroke:#000
    classDef storage fill:#D3D3D3,stroke:#000

    click ExperimentsYML "https://github.com/lamalab-org/photocat-hte/blob/main/config/experiments.yml"
    click SetupYML "https://github.com/lamalab-org/photocat-hte/blob/main/config/setup.yml"
    click ExperimentYML "https://github.com/lamalab-org/photocat-hte/blob/main/config/experiment.yml"
    click MainPY "https://github.com/lamalab-org/photocat-hte/blob/main/src/photolooper/main.py"
    click RunPY "https://github.com/lamalab-org/photocat-hte/blob/main/experiments/run.py"
    click FirestingDriver "https://github.com/lamalab-org/photocat-hte/blob/main/src/photolooper/firesting.py"
    click PowersupplyDriver "https://github.com/lamalab-org/photocat-hte/blob/main/src/photolooper/powersupply.py"
    click Status "https://github.com/lamalab-org/photocat-hte/blob/main/src/photolooper/status.py"
    click Utils "https://github.com/lamalab-org/photocat-hte/blob/main/src/photolooper/utils.py"
    click RXN_ODE "https://github.com/lamalab-org/photocat-hte/blob/main/src/photolooper/rxn_ode_fitting.py"
    click Fit "https://github.com/lamalab-org/photocat-hte/blob/main/src/photolooper/fit.py"
    click DataFit "https://github.com/lamalab-org/photocat-hte/blob/main/data_analysis/data_fit_analysis.py"
    click RateAnalysis "https://github.com/lamalab-org/photocat-hte/blob/main/data_analysis/rate_analysis.py"
    click ProcessedCSVStorage "https://github.com/lamalab-org/photocat-hte/tree/main/data_analysis/csv/"
    click ProcessedJSONStorage "https://github.com/lamalab-org/photocat-hte/tree/main/data_analysis/json/"
    click Visualizations "https://github.com/lamalab-org/photocat-hte/tree/main/data_analysis/Visualizations/"
```
