DeepSANE

Deep-learning & Symmetry-Adapted, Ab-initio Nuclear modeling — an AI-ready Ecosystem

A modern collection of symmetry-adapted scientific codes engineered for community adoption and agentic systems.

DeepSANE is a computational ecosystem uniting first-principles nuclear physics, symmetry-adapted modeling, and modern artificial intelligence.

Our mission is two-fold:

1. Community Adoption: Provide an open, modular, and high-performance collection of scientific codes from foundational Lie group algebras and sparse solvers to ab initio nuclear simulations and machine-learning models, engineered with clean interfaces, modern standards, and reproducible workflows for the broader physics and scientific computing communities.
2. AI & Agentic Readiness: DeepSANE libraries are designed from the ground up for modern AI workflows and deployment into agentic systems. With self-describing skill layers, structured task catalogs, and automated execution lifecycles, autonomous coding agents can directly interface with, reason about, and orchestrate complex scientific calculations.

DeepSANE is engineered modularly. Low-level algebraic and mathematical engines stand independently, allowing researchers to adopt them in isolation or compose them into full ab initio nuclear simulations.

flowchart TD
    classDef standalone fill:#EBF8FF,stroke:#3182CE,stroke-width:2px,color:#2B6CB0,font-weight:bold
    classDef intermediate fill:#E6FFFA,stroke:#319795,stroke-width:2px,color:#234E52,font-weight:bold
    classDef flagship fill:#FEFCBF,stroke:#D69E2E,stroke-width:2px,color:#744210,font-weight:bold
    classDef ml fill:#FAF5FF,stroke:#805AD5,stroke-width:2px,color:#44337A,font-weight:bold

    subgraph Tier1 ["Tier 1: Standalone Foundations"]
        KRANS["KraNS<br/><code>Matrix-Free Null Space</code>"]:::standalone
        UNTOU3["UNtoU3<br/><code>U(N) → U(3) Branching</code>"]:::standalone
        WIGNER["Wigner-mass-public<br/><code>Symmetry-Inspired ML Masses</code>"]:::ml
    end

    subgraph Tier2 ["Tier 2 & 3: Lie Symmetry Algebras"]
        U3["u3lib<br/><code>U(3) Coupling & Recoupling</code>"]:::intermediate
        U4["u4lib<br/><code>U(4) Coupling & Recoupling</code>"]:::intermediate
    end

    subgraph Tier4 ["Tier 4: Flagship Ab Initio Simulation"]
        SAM["SAM<br/><code>Symmetry Adapted Many-Body Calculations</code>"]:::flagship
    end

    KRANS --> U3
    KRANS --> U4
    U3 --> U4

    KRANS --> SAM
    UNTOU3 --> SAM
    U3 --> SAM
    U4 --> SAM

Before building the DeepSANE ecosystem, ensure your development environment satisfies the following toolchain requirements:

• Version Control: git must be installed (git --version) to clone and manage repositories.
• C++ Compiler (C++20 & OpenMP):

  [!WARNING] macOS Users — Avoid Apple Clang: The default Apple Clang compiler (/usr/bin/clang++ bundled with Xcode Command Line Tools) lacks native OpenMP support, which is essential for parallel multi-threaded performance across DeepSANE.

  • Recommended on macOS: Install modern GCC via Homebrew:

    brew install gcc
    export CXX=g++-14   # or g++-13 / g++-12 depending on your installed brew version
    export CC=gcc-14

  • Alternatively, install Homebrew LLVM with libomp (brew install llvm libomp).
  • Linux / HPC Clusters: GCC 11+ (GCC 12/13/14 recommended) or Intel oneAPI (icpx) with standard OpenMP support.

• Build Tools: CMake $\ge$ 3.16 and GNU make.
• Python Environment: Python $\ge$ 3.10 with pip (recommended: a dedicated virtual environment or Conda environment) for machine learning mass models in Wigner-mass-public.

Because higher-tier libraries link against the compiled artifacts or header interfaces of lower-tier packages, we recommend installing the ecosystem in the following sequence:

These libraries have no internal dependencies within DeepSANE and can be installed independently:

1. KraNS.
2. untou3.
3. Wigner-mass-public.

u3lib uses KraNS for high-performance null-space basis computations.

u4lib depends on both u3lib and KraNS.

SAM (Symmetry Adapted Model) brings together all foundational components to execute ab initio nuclear structure simulations.

The DeepSANE ecosystem is developed and maintained through collaborative research bridging nuclear physics, applied mathematics, computer systems, and machine learning:

• Jerry P. Draayer (Louisiana State University, in memoriam) — Foundational algebraic formulations & symmetry lineage
• Feng Pan (Huzhou Normal University) — Algebraic methods & nuclear theory
• David Kekejian (Quantum CodeX) — Nuclear theory
• Alexandr Krastenov (Czech Technical University in Prague) — Nullspace solvers
• Evander Espinoza (Louisiana State University) — Physics-Informed ML