How gt-nucleicacids/pnab works
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.