# hekstra-lab/sfcalculator_torch architecture

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

- Interactive diagram: https://gitdiagram.com/hekstra-lab/sfcalculator_torch
- Repository: https://github.com/hekstra-lab/sfcalculator_torch

## Overview

##### Project type and purpose
- This is an open‑source Python library (packaged on PyPI) that provides a PyTorch implementation of crystallographic structure‐factor calculations (SFcalculator).
- Its goal is to read crystallographic data files (CIF, MTZ, PDB), process them (voxelization, masking, symmetry operations, packing score), compute structure factors, and derive Patterson maps—all using PyTorch tensors for GPU acceleration.

##### File structure
- Top‐level packaging/configuration:
- setup.py, setup.cfg, MANIFEST.in → Python package metadata & installation
- .github/workflows → CI/CD for build, test, and publish
- Source code directory: `SFC_Torch/`
- io.py → parsers for CIF/MTZ/PDB files and data loaders
- mask.py → mask‐generation routines
- voxel.py → voxelization of electron density
- symmetry.py → symmetry‐operation generators
- packingscore.py → molecular packing‐score computations
- Fmodel.py → computation of structure factors (core SFcalculator logic)
- patterson.py → Patterson‐map calculation
- utils.py → shared utilities (e.g., tensor conversions, constants)
- Test suite in `tests/` exercising each module and sample data files

##### Extract insights from the README
- Confirms PyTorch dependency
- Installation steps: environment → install PyTorch → pip install SFcalculator‑torch
- Citations & badges show active CI, code coverage, and PyPI publication

a. Main components
1. External Inputs (CIF, MTZ, PDB files)
2. io.Parser Module
3. Preprocessing Modules
– mask
– voxel
– symmetry
– utils (shared helpers)
4. Core Computational Modules
– packingscore
– Fmodel (structure‐factor engine)
– patterson (Patterson map engine)
5. Outputs
– Structure‐factor arrays
– Patterson maps
6. Non‑functional/Infrastructure
– Python Environment & Dependencies (PyTorch)
– CI/CD Pipeline (GitHub Actions → test & publish)
– Packaging (setup.py → PyPI)

b. Relationships & data flow
- utils is connected bidirectionally to all modules that need shared code

c. Architectural patterns & principles
- Layered (Input → Preprocessing → Core → Output)
- Modular design (each scientific operation in its own module)
- Pipeline pattern (sequential transformations on tensor data)
- Dependency inversion for utilities

d. Key technologies/frameworks
- Python 3.x
- PyTorch (tensor operations, GPU acceleration)
- pytest (tests)
- GitHub Actions (CI/CD)
- packaging: setuptools (setup.py, setup.cfg)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Stage
    subgraph "Stage: Input"
        ExtInputs["External Inputs\n(CIF/MTZ/PDB)"]:::input
    end

    %% Parsing Stage
    subgraph "Stage: Parsing"
        IO["io.Parser Module"]:::module
    end

    %% Preprocessing Stage
    subgraph "Stage: Preprocessing"
        Mask["mask"]:::module
        Voxel["voxel"]:::module
        Symmetry["symmetry"]:::module
        Utils["utils"]:::utility
    end

    %% Core Computation Stage
    subgraph "Stage: Core Computation"
        Packing["packingscore"]:::module
        Fmodel["Fmodel"]:::module
        Patterson["patterson"]:::module
    end

    %% Output Stage
    subgraph "Stage: Output"
        SFOut["Structure-Factor Arrays"]:::output
        PMOut["Patterson Maps"]:::output
    end

    %% Testing Stage
    subgraph "Stage: Testing"
        Tests["Test Suite"]:::testing
    end

    %% Infrastructure & Packaging
    subgraph "Infrastructure & Packaging"
        Env["Python Environment & PyTorch"]:::infra
        CI["CI/CD Pipeline"]:::infra
        Package["Packaging Config"]:::infra
    end

    %% Data Flow
    ExtInputs --> IO
    IO --> Mask
    Mask --> Voxel
    Voxel --> Symmetry
    Symmetry --> Packing
    Symmetry --> Fmodel
    Fmodel --> Patterson
    Packing --> SFOut
    Fmodel --> SFOut
    Patterson --> PMOut

    %% Utilities Dependencies
    Utils <--> IO
    Utils <--> Mask
    Utils <--> Voxel
    Utils <--> Symmetry
    Utils <--> Packing
    Utils <--> Fmodel
    Utils <--> Patterson

    %% Infra Connections
    Env --> IO
    Env --> Mask
    Env --> Voxel
    Env --> Symmetry
    Env --> Packing
    Env --> Fmodel
    Env --> Patterson
    CI --> Tests
    CI --> Package

    %% Click Events
    click ExtInputs "https://github.com/hekstra-lab/sfcalculator_torch/tree/master/tests/data/"
    click IO "https://github.com/hekstra-lab/sfcalculator_torch/blob/master/SFC_Torch/io.py"
    click Mask "https://github.com/hekstra-lab/sfcalculator_torch/blob/master/SFC_Torch/mask.py"
    click Voxel "https://github.com/hekstra-lab/sfcalculator_torch/blob/master/SFC_Torch/voxel.py"
    click Symmetry "https://github.com/hekstra-lab/sfcalculator_torch/blob/master/SFC_Torch/symmetry.py"
    click Utils "https://github.com/hekstra-lab/sfcalculator_torch/blob/master/SFC_Torch/utils.py"
    click Packing "https://github.com/hekstra-lab/sfcalculator_torch/blob/master/SFC_Torch/packingscore.py"
    click Fmodel "https://github.com/hekstra-lab/sfcalculator_torch/blob/master/SFC_Torch/Fmodel.py"
    click Patterson "https://github.com/hekstra-lab/sfcalculator_torch/blob/master/SFC_Torch/patterson.py"
    click Package "https://github.com/hekstra-lab/sfcalculator_torch/blob/master/setup.py"
    click CI "https://github.com/hekstra-lab/sfcalculator_torch/blob/master/.github/workflows/Build.yml"
    click Tests "https://github.com/hekstra-lab/sfcalculator_torch/tree/master/tests/"

    %% Styles
    classDef input fill:#9fdfbf,stroke:#333,stroke-width:1px;
    classDef module fill:#add8e6,stroke:#333,stroke-width:1px;
    classDef utility fill:#d3d3ff,stroke:#333,stroke-width:1px;
    classDef output fill:#ffdead,stroke:#333,stroke-width:1px;
    classDef infra fill:#cccccc,stroke:#333,stroke-width:1px;
    classDef testing fill:#e6e6fa,stroke:#333,stroke-width:1px;
```
