# cryotud/locscale architecture

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

- Interactive diagram: https://gitdiagram.com/cryotud/locscale
- Repository: https://github.com/cryotud/locscale

## Overview

##### Project type and purpose
- LocScale-2.0 is an open-source Python-based map-optimization program for cryo-EM data.
- It provides a command-line interface (CLI), orchestrates preprocessing, invokes CPU/GPU neural-net modules (EMmerNet), wraps Fortran/C libraries (symmetry, map utilities), and optionally calls external executables (REFMAC5).

##### File structure
Top-level directories & files:
- `locscale/main.py` – CLI entrypoint.
- `config.py` – global settings.
- `locscale/automate/…` – helper scripts and orchestration tools.
- `locscale/preprocessing/…` – pipeline definition, data validation, pseudomodel generation.
- `locscale/emmernet/…` – deep-learning-based map optimization.
- `locscale/include/…` – wrapped Fortran/Python libraries for confidence mapping, symmetry, EMmer, pdb handling.
- `locscale/utils/…` – I/O, math, plotting, file-tools.
- `locscale/tests/…` – unit and integration tests.
- `docs/`, `mkdocs.yml` – documentation infrastructure.

##### README for insights
- Confirms the four main modes: feature-enhanced maps, hybrid sharpening, model-free sharpening, legacy mode.
- Mentions the external dependency REFMAC5 (must be on PATH).
- Advises GPU usage for EMmerNet.

##### Main components & how they interact
a. CLI Layer (locscale/main.py)
- Parses user inputs, mode selection, file paths, config.
b. Configuration Module (config.py)
- Reads environment variables, default parameters, paths to external executables (e.g., `refmac5`).
c. Orchestration / Automation (locscale/automate)
- Builds & sequences tasks: preprocessing → map optimization → postprocessing.
d. Preprocessing Pipeline (locscale/preprocessing)
- /model input validation
- Generation of pseudomodels (if needed)
- Data preparation for EMmerNet or confidence maps
e. Core Processing Engines
- EMmerNet Module (locscale/emmernet)
– GPU/CPU routines for neural network-based sharpening.
- Confidence–Map Utilities (locscale/include/confidenceMapUtil)
– Python wrappers around FDRutil, locscaleUtil, mapUtil.
- Symmetry Routines (locscale/include/symmetry_emda)
– Fortran/C code for point-group operations.
- EMmer Wrappers (locscale/include/emmer)
– NDImage & PDB utilities from the EMmer library.
f. External Executable
- REFMAC5
– Invoked for model-based and hybrid sharpening.
g. Utilities (locscale/utils)
- File I/O, mathematical tools, plotting, process launching.
h. Tests (locscale/tests)
- Validate each component in isolation and end-to-end.

##### Architectural patterns & design principles
- Pipeline/Orchestrator pattern – tasks flow in stages.
- Modular subpackages for each functional area (single responsibility).
- Wrapping of native Fortran/C code behind Python APIs.
- Plugin-style modes (feature enhanced, hybrid, model-free) selected by CLI flags.
- Clear separation of CLI, core logic, and external dependencies.

##### Essential elements
- Clear component names (e.g., “Preprocessing Pipeline”).
- Callouts for key configuration (e.g., `REFMAC5_PATH` in config.py).

## Diagram (Mermaid)

```mermaid
flowchart TD
    classDef python fill:#D6EAF8,stroke:#1B4F72,color:#1B2631;
    classDef native fill:#D5F5E3,stroke:#196F3D,color:#145A32;
    classDef external fill:#FCF3CF,stroke:#7D6608,color:#7D6608;
    classDef data fill:#F4F6F7,stroke:#85929E,color:#2C3E50;

    subgraph "CLI & Config"
        CLI["CLI Layer\n(locscale/main.py)"]:::python
        Config["Configuration Module\n(config.py)"]:::python
    end

    subgraph "Orchestrator & Preprocessor"
        Orch["Orchestration/Automation\n(locscale/automate)"]:::python
        Pre["Preprocessing Pipeline\n(locscale/preprocessing)"]:::python
    end

    subgraph "Processing Engines"
        EM["EMmerNet Module\n(locscale/emmernet)"]:::python
        Conf["Confidence-Map Utilities"]:::native
        Sym["Symmetry Routines"]:::native
        Emwr["EMmer Wrappers"]:::native
    end

    subgraph "External Systems"
        Refmac["REFMAC5 Executable"]:::external
    end

    subgraph "Utilities & Tests"
        Utils["Utilities\n(locscale/utils)"]:::python
        Tests["Tests\n(locscale/tests)"]:::python
    end

    subgraph "Data Artifacts"
        Pseudo["Pseudomodel CIF"]:::data
        Sharpened["Sharpened Map (.mrc)"]:::data
    end

    %% Control & data flow
    CLI -->|parses inputs| Orch
    CLI -->|reads settings| Config
    Config -->|provides params| Orch

    Orch -->|sequence tasks| Pre
    Pre -->|".mrc map"| EM
    Pre -->|"initial map"| Conf
    Pre -->|"input map"| Sym
    Pre -->|"model data"| Emwr
    Pre -->|generates| Pseudo

    EM -->|"logs/status"| Orch
    Conf -->|"logs/status"| Orch
    Sym -->|"logs/status"| Orch
    Emwr -->|"logs/status"| Orch

    Orch -.->|calls refmac5| Refmac
    Refmac -.->|returns outputs| Orch

    Orch -->|outputs| Sharpened

    Orch -->|uses| Utils
    Pre -->|uses| Utils
    EM -->|uses| Utils

    Tests -->|validates| CLI
    Tests -->|validates| Orch
    Tests -->|validates| EM
    Tests -->|validates| Sym

    %% Click events
    click CLI "https://github.com/cryotud/locscale/blob/master/locscale/main.py"
    click Config "https://github.com/cryotud/locscale/blob/master/config.py"
    click Orch "https://github.com/cryotud/locscale/blob/master/locscale/automate/tools.py"
    click Pre "https://github.com/cryotud/locscale/blob/master/locscale/preprocessing/pipeline.py"
    click EM "https://github.com/cryotud/locscale/blob/master/locscale/emmernet/run_emmernet.py"
    click Conf "https://github.com/cryotud/locscale/blob/master/locscale/include/confidenceMapUtil/confidenceMapMain.py"
    click Sym "https://github.com/cryotud/locscale/blob/master/locscale/include/symmetry_emda/GenerateOperators_v9_ky4.py"
    click Emwr "https://github.com/cryotud/locscale/blob/master/locscale/include/emmer/headers.py"
    click Utils "https://github.com/cryotud/locscale/blob/master/locscale/utils/file_tools.py"
    click Tests "https://github.com/cryotud/locscale/blob/master/locscale/tests/test_locscale.py"
```
