# gt-nucleicacids/pnab architecture

> Architecture diagram of the GitHub repository gt-nucleicacids/pnab, 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/gt-nucleicacids/pnab
- Repository: https://github.com/gt-nucleicacids/pnab

## Overview

##### Project Type and Purpose
- Type: Scientific modeling library and command-line tool with a Python API and Jupyter-based GUI.
- Purpose: Construct 3D structures of DNA/RNA analogs via helical parameter searches and energetic/ geometric evaluations.

##### File Structure
- Top-level build & config:
– CMakeLists.txt, cmake/modules (FindEigen, FindOpenBabel) → orchestrate C++ core build.
– conda_recipe/ → conda packaging metadata & scripts.
- Core computation (C++):
– pnab/src/Chain.cpp/.h, ConformationSearch.cpp/.h, Containers.cpp/.h, binder.cpp → implements search algorithms, data structures, and PyBind11 bindings.
- Python package (pnab/):
– __init__.py, extras.py, data/ (PDB & YAML templates), driver/ (driver.py CLI entrypoint, options.py, jupyter_widgets.py) → exposes C++ library in Python, handles CLI, Jupyter GUI.
- Documentation:
– Doxygen/ + docs/html & docs/latex → auto-generated API docs.
- Interactive front end:
– binder/driver.ipynb → demonstration via Jupyter notebook with widgets.
- Testing:
– tests/ (pytest-based, using sample data files) → validates binding, driver behavior, energy filters.

##### README for Insights
- Languages: C++ for core, Python for wrapping and GUI.
- Dependencies: Eigen (linear algebra), OpenBabel (molecular formats), PyBind11 (bindings).
- Platforms: Linux, MacOS, Windows (via CMake and conda).
- Interfaces: CLI, conda-installable library, Jupyter widgets.

##### Main Components & Their Relationships
a. C++ Core Library
– Implements geometry, energy evaluation, conformation & helical searches.
– Built by CMake, depends on Eigen & OpenBabel.
b. Python Bindings (binder.cpp via PyBind11)
– Exposes C++ classes/functions to Python as module `pnab`.
c. Python Driver & CLI (`pnab/driver/driver.py`)
– Parses user options, invokes the `pnab` module for structure building; outputs PDB or CSV.
d. Data Repository (`pnab/data/`)
– YAML & PDB templates for backbone and bases.
e. Jupyter GUI (`pnab/driver/jupyter_widgets.py` + binder notebook)
f. Packaging & Deployment
– conda_recipe/ for distribution, install.sh/install.bat scripts, CI workflows (.github, appveyor.yml).
g. Documentation & Tests
– Doxygen pipelines generate HTML/LaTeX docs.
– pytest suite exercises Python bindings and driver logic against sample data.

##### Important Architectural Patterns & Principles
- Separation of concerns:
‑ Computational kernel (C++)
‑ Language binding layer (PyBind11)
‑ High-level orchestration & UI (Python CLI, Jupyter)
- Extensibility: new nucleic acid types added via data files, not code changes.
- Cross-platform build: CMake + conda recipe abstracts away OS differences.
- Documentation pipeline: source code → Doxygen → HTML/LaTeX → hosted docs.

- CMake → compiles C++ sources using Eigen & OpenBabel → produces `libpnab` and `pnab` Python extension.
- Python package installation (conda) feeding into CLI script entrypoint.
- Separate CLI workflow from Jupyter workflow, but both depending on the same Python API.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies
    subgraph "External Libraries"
        direction TB
        Eigen["Eigen"]:::external
        OpenBabel["OpenBabel"]:::external
    end

    %% Build System
    CMake["CMake Build\n(CMakeLists.txt,\ncmake/modules)"]:::cpp
    click CMake "https://github.com/gt-nucleicacids/pnab/blob/master/CMakeLists.txt"
    click CMake "https://github.com/gt-nucleicacids/pnab/tree/master/cmake/modules"

    %% C++ Core
    subgraph "C++ Core Library" 
        direction TB
        Core["pnab/src/"]:::cpp
    end
    click Core "https://github.com/gt-nucleicacids/pnab/tree/master/pnab/src/"

    %% Binding Layer
    Binding["PyBind11 Binding\n(binder.cpp)"]:::cpp
    click Binding "https://github.com/gt-nucleicacids/pnab/blob/master/pnab/src/binder.cpp"

    %% Python API & Package
    subgraph "Python Package" 
        direction TB
        Init["pnab/__init__.py"]:::python
        Extras["pnab/extras.py"]:::python
    end
    click Init "https://github.com/gt-nucleicacids/pnab/blob/master/pnab/__init__.py"
    click Extras "https://github.com/gt-nucleicacids/pnab/blob/master/pnab/extras.py"

    %% Data Templates
    Data["YAML & PDB Templates\n(pnab/data/)"]:::external
    click Data "https://github.com/gt-nucleicacids/pnab/tree/master/pnab/data/"

    %% Python Interfaces
    subgraph "Python Interfaces" 
        direction TB
        CLI["CLI Driver\n(driver.py & options.py)"]:::python
        Jupyter["Jupyter GUI\n(jupyter_widgets.py & notebook)"]:::python
    end
    click CLI "https://github.com/gt-nucleicacids/pnab/blob/master/pnab/driver/driver.py"
    click CLI "https://github.com/gt-nucleicacids/pnab/blob/master/pnab/driver/options.py"
    click Jupyter "https://github.com/gt-nucleicacids/pnab/blob/master/pnab/driver/jupyter_widgets.py"
    click Jupyter "https://github.com/gt-nucleicacids/pnab/blob/master/binder/driver.ipynb"

    %% Packaging & CI
    subgraph "Packaging & CI" 
        direction TB
        Conda["conda_recipe/"]:::pkg
        Install["install.sh & install.bat"]:::pkg
        CI1[".github/workflows/\nbuild_linux_macos.yml"]:::pkg
        CI2["appveyor.yml"]:::pkg
    end
    click Conda "https://github.com/gt-nucleicacids/pnab/tree/master/conda_recipe/"
    click CI1 "https://github.com/gt-nucleicacids/pnab/blob/master/.github/workflows/build_linux_macos.yml"
    click CI2 "https://github.com/gt-nucleicacids/pnab/blob/master/appveyor.yml"

    %% Documentation
    subgraph "Documentation"
        direction TB
        Doxy["Doxygen/"]:::pkg
        DocHTML["docs/html/"]:::pkg
        DocLaTeX["docs/latex/"]:::pkg
    end
    click Doxy "https://github.com/gt-nucleicacids/pnab/tree/master/Doxygen/"
    click DocHTML "https://github.com/gt-nucleicacids/pnab/tree/master/docs/html/"
    click DocLaTeX "https://github.com/gt-nucleicacids/pnab/tree/master/docs/latex/"

    %% Testing
    Tests["tests/"]:::pkg
    click Tests "https://github.com/gt-nucleicacids/pnab/tree/master/tests/"

    %% Outputs
    Outputs["Output PDB/CSV Files"]:::external

    %% Relationships
    Eigen --> CMake
    OpenBabel --> CMake
    CMake --> Core
    CMake --> Binding
    Core --> Binding
    Binding --> Init
    Binding --> Extras
    Init --> CLI
    Extras --> CLI
    Init --> Jupyter
    Extras --> Jupyter
    CLI --> Outputs
    Jupyter --> Outputs
    CLI --> Data
    Jupyter --> Data
    Tests --> Init
    Tests --> Extras
    Tests --> Data
    Doxy --> Core
    Doxy --> Binding
    Conda --> Init
    Conda --> Extras
    Conda --> CLI
    Conda --> Jupyter
    Install --> Conda

    %% Styles
    classDef cpp fill:#cce5ff,stroke:#004085,color:#004085
    classDef python fill:#d4edda,stroke:#155724,color:#155724
    classDef external fill:#fff3cd,stroke:#856404,color:#856404,stroke-dasharray: 5 5
    classDef pkg fill:#e2e3e5,stroke:#6c757d,color:#383d41,stroke-dasharray: 5 5
```
