# microsoft/skala architecture

> Architecture diagram of the GitHub repository microsoft/skala, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/microsoft/skala
- Repository: https://github.com/microsoft/skala

## Overview

Skala is a neural exchange-correlation functional used in DFT calculations. The main workflow is to select/load a functional, construct a PySCF or GPU4PySCF Kohn–Sham calculator (or use the ASE adapter), evaluate atomic-orbital features on grids, and obtain energies and gradients; optional DFT-D3 adds dispersion. The repository also contains a separate trainable model definition and GauXC export support. Edges reflect README statements or source-index references; unsampled implementation details are not inferred.

Main entry points: [`skala/src/skala/pyscf/dft.py`](https://github.com/microsoft/skala/blob/main/skala/src/skala/pyscf/dft.py) (PySCF KS engine), [`skala/src/skala/gpu4pyscf/dft.py`](https://github.com/microsoft/skala/blob/main/skala/src/skala/gpu4pyscf/dft.py) (GPU KS engine), [`skala/src/skala/pyscf/__init__.py`](https://github.com/microsoft/skala/blob/main/skala/src/skala/pyscf/__init__.py) (PySCF workflow), [`model/src/skala_model/model.py`](https://github.com/microsoft/skala/blob/main/model/src/skala_model/model.py) (Trainable Skala model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_pyscf["PySCF workflow<br/>[__init__.py]"]
  node_gpu["GPU4PySCF workflow<br/>[dft.py]"]
  node_ase["ASE calculator<br/>[calculator.py]"]
end

subgraph group_functionals["Functional runtime"]
  node_functional_loader["Functional loader<br/>[__init__.py]"]
  node_traced["Traced functional<br/>[base.py]"]
  node_traditional["Traditional functionals<br/>[traditional.py]"]
  node_features["Feature schema<br/>[features.py]"]
end

subgraph group_engine["DFT evaluation"]
  node_ao_eval["AO evaluation<br/>[ao_evaluation.py]"]
  node_feature_math["Feature math<br/>[feature_math.py]"]
  node_chunking["Model chunking<br/>[model_chunking.py]"]
  node_numint["Numerical integration<br/>[numint.py]"]
  node_pyscf_dft["PySCF KS engine<br/>[dft.py]"]
  node_gradients["PySCF gradients<br/>[gradient_core.py]"]
  node_backend["Backend selection<br/>[backend.py]"]
  node_grids["Grid management<br/>[grids.py]"]
  node_dispersion["DFT-D3 adapter<br/>[dispersion.py]"]
  node_gpu_dft["GPU KS engine<br/>[dft.py]"]
  node_gpu_gradients["GPU gradients<br/>[gradients.py]"]
end

subgraph group_development["Model and export"]
  node_skala_model["Trainable Skala model<br/>[model.py]"]
  node_layers["Model layers<br/>[layers.py]"]
  node_irreps["Irrep utilities<br/>[irreps.py]"]
  node_contraction["Symmetric contraction"]
  node_exporter["GauXC exporter<br/>[export.py]"]
end

node_user(("DFT user"))
node_checkpoint_service["Model hosting"]
node_pyscf_service["PySCF library"]
node_gpu_service["GPU4PySCF library"]
node_ase_service["ASE library"]
node_gauxc_service["GauXC integration"]

node_user -->|"runs calculation"| node_pyscf
node_user -->|"runs calculation"| node_gpu
node_user -->|"requests energy"| node_ase
node_pyscf -->|"loads functional"| node_functional_loader
node_gpu -->|"loads functional"| node_functional_loader
node_functional_loader -->|"downloads checkpoint"| node_checkpoint_service
node_functional_loader -->|"loads artifact"| node_traced
node_functional_loader -->|"selects functional"| node_traditional
node_traced -->|"consumes features"| node_features
node_traditional -->|"consumes features"| node_features
node_pyscf -->|"constructs KS"| node_pyscf_dft
node_gpu -->|"constructs KS"| node_gpu_dft
node_ase -->|"uses calculator"| node_pyscf
node_pyscf_dft -->|"configures integration"| node_numint
node_pyscf_dft -->|"provides gradients"| node_gradients
node_pyscf_dft -->|"configures grids"| node_grids
node_pyscf_dft -->|"adds correction"| node_dispersion
node_numint -->|"evaluates chunks"| node_chunking
node_chunking -->|"evaluates AO features"| node_ao_eval
node_chunking -->|"transforms features"| node_feature_math
node_ao_eval -->|"uses feature operators"| node_feature_math
node_pyscf_dft -->|"selects backend"| node_backend
node_gpu_dft -->|"provides gradients"| node_gpu_gradients
node_gpu_dft -->|"uses grid support"| node_grids
node_gpu_dft -->|"adds correction"| node_dispersion
node_gpu_dft -->|"uses integration"| node_numint
node_gpu_dft -->|"extends library"| node_gpu_service
node_pyscf -->|"integrates with"| node_pyscf_service
node_ase -->|"implements adapter"| node_ase_service
node_skala_model -->|"uses feature schema"| node_features
node_skala_model -->|"implements functional base"| node_traced
node_skala_model -->|"uses layers"| node_layers
node_skala_model -->|"uses irreps"| node_irreps
node_skala_model -->|"uses contraction"| node_contraction
node_exporter -->|"references integration"| node_pyscf
node_exporter -->|"exports for"| node_gauxc_service

click node_pyscf "https://github.com/microsoft/skala/blob/main/skala/src/skala/pyscf/__init__.py"
click node_gpu "https://github.com/microsoft/skala/blob/main/skala/src/skala/gpu4pyscf/dft.py"
click node_ase "https://github.com/microsoft/skala/blob/main/skala/src/skala/ase/calculator.py"
click node_functional_loader "https://github.com/microsoft/skala/blob/main/skala/src/skala/functional/__init__.py"
click node_traced "https://github.com/microsoft/skala/blob/main/skala/src/skala/functional/base.py"
click node_traditional "https://github.com/microsoft/skala/blob/main/skala/src/skala/functional/traditional.py"
click node_features "https://github.com/microsoft/skala/blob/main/skala/src/skala/features.py"
click node_ao_eval "https://github.com/microsoft/skala/blob/main/skala/src/skala/pyscf/ao_evaluation.py"
click node_feature_math "https://github.com/microsoft/skala/blob/main/skala/src/skala/pyscf/feature_math.py"
click node_chunking "https://github.com/microsoft/skala/blob/main/skala/src/skala/pyscf/model_chunking.py"
click node_numint "https://github.com/microsoft/skala/blob/main/skala/src/skala/pyscf/numint.py"
click node_pyscf_dft "https://github.com/microsoft/skala/blob/main/skala/src/skala/pyscf/dft.py"
click node_gradients "https://github.com/microsoft/skala/blob/main/skala/src/skala/pyscf/gradient_core.py"
click node_backend "https://github.com/microsoft/skala/blob/main/skala/src/skala/pyscf/backend.py"
click node_grids "https://github.com/microsoft/skala/blob/main/skala/src/skala/pyscf/grids.py"
click node_dispersion "https://github.com/microsoft/skala/blob/main/skala/src/skala/dispersion.py"
click node_gpu_dft "https://github.com/microsoft/skala/blob/main/skala/src/skala/gpu4pyscf/dft.py"
click node_gpu_gradients "https://github.com/microsoft/skala/blob/main/skala/src/skala/gpu4pyscf/gradients.py"
click node_skala_model "https://github.com/microsoft/skala/blob/main/model/src/skala_model/model.py"
click node_layers "https://github.com/microsoft/skala/blob/main/model/src/skala_model/layers.py"
click node_irreps "https://github.com/microsoft/skala/blob/main/model/src/skala_model/utils/irreps.py"
click node_contraction "https://github.com/microsoft/skala/blob/main/model/src/skala_model/utils/symmetric_contraction.py"
click node_exporter "https://github.com/microsoft/skala/blob/main/gauxc/src/skala_gauxc/export.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_pyscf,node_gpu,node_ase,node_user toneBlue
class node_functional_loader,node_traced,node_traditional,node_features toneAmber
class node_ao_eval,node_feature_math,node_chunking,node_numint,node_pyscf_dft,node_gradients,node_backend,node_grids,node_dispersion,node_gpu_dft,node_gpu_gradients toneMint
class node_skala_model,node_layers,node_irreps,node_contraction,node_exporter toneRose
class node_checkpoint_service,node_pyscf_service,node_gpu_service,node_ase_service,node_gauxc_service toneIndigo
```

## Components

### User interfaces

- [PySCF workflow](https://github.com/microsoft/skala/blob/main/skala/src/skala/pyscf/__init__.py): `skala/src/skala/pyscf/__init__.py`
- [GPU4PySCF workflow](https://github.com/microsoft/skala/blob/main/skala/src/skala/gpu4pyscf/dft.py): `skala/src/skala/gpu4pyscf/dft.py`
- [ASE calculator](https://github.com/microsoft/skala/blob/main/skala/src/skala/ase/calculator.py): `skala/src/skala/ase/calculator.py`

### Functional runtime

- [Functional loader](https://github.com/microsoft/skala/blob/main/skala/src/skala/functional/__init__.py): `skala/src/skala/functional/__init__.py`
- [Traced functional](https://github.com/microsoft/skala/blob/main/skala/src/skala/functional/base.py): `skala/src/skala/functional/base.py`
- [Traditional functionals](https://github.com/microsoft/skala/blob/main/skala/src/skala/functional/traditional.py): `skala/src/skala/functional/traditional.py`
- [Feature schema](https://github.com/microsoft/skala/blob/main/skala/src/skala/features.py): `skala/src/skala/features.py`

### DFT evaluation

- [AO evaluation](https://github.com/microsoft/skala/blob/main/skala/src/skala/pyscf/ao_evaluation.py): `skala/src/skala/pyscf/ao_evaluation.py`
- [Feature math](https://github.com/microsoft/skala/blob/main/skala/src/skala/pyscf/feature_math.py): `skala/src/skala/pyscf/feature_math.py`
- [Model chunking](https://github.com/microsoft/skala/blob/main/skala/src/skala/pyscf/model_chunking.py): `skala/src/skala/pyscf/model_chunking.py`
- [Numerical integration](https://github.com/microsoft/skala/blob/main/skala/src/skala/pyscf/numint.py): `skala/src/skala/pyscf/numint.py`
- [PySCF KS engine](https://github.com/microsoft/skala/blob/main/skala/src/skala/pyscf/dft.py): `skala/src/skala/pyscf/dft.py`
- [PySCF gradients](https://github.com/microsoft/skala/blob/main/skala/src/skala/pyscf/gradient_core.py): `skala/src/skala/pyscf/gradient_core.py`
- [Backend selection](https://github.com/microsoft/skala/blob/main/skala/src/skala/pyscf/backend.py): `skala/src/skala/pyscf/backend.py`
- [Grid management](https://github.com/microsoft/skala/blob/main/skala/src/skala/pyscf/grids.py): `skala/src/skala/pyscf/grids.py`
- [DFT-D3 adapter](https://github.com/microsoft/skala/blob/main/skala/src/skala/dispersion.py): `skala/src/skala/dispersion.py`
- [GPU KS engine](https://github.com/microsoft/skala/blob/main/skala/src/skala/gpu4pyscf/dft.py): `skala/src/skala/gpu4pyscf/dft.py`
- [GPU gradients](https://github.com/microsoft/skala/blob/main/skala/src/skala/gpu4pyscf/gradients.py): `skala/src/skala/gpu4pyscf/gradients.py`

### Model and export

- [Trainable Skala model](https://github.com/microsoft/skala/blob/main/model/src/skala_model/model.py): `model/src/skala_model/model.py`
- [Model layers](https://github.com/microsoft/skala/blob/main/model/src/skala_model/layers.py): `model/src/skala_model/layers.py`
- [Irrep utilities](https://github.com/microsoft/skala/blob/main/model/src/skala_model/utils/irreps.py): `model/src/skala_model/utils/irreps.py`
- [Symmetric contraction](https://github.com/microsoft/skala/blob/main/model/src/skala_model/utils/symmetric_contraction.py): `model/src/skala_model/utils/symmetric_contraction.py`
- [GauXC exporter](https://github.com/microsoft/skala/blob/main/gauxc/src/skala_gauxc/export.py): `gauxc/src/skala_gauxc/export.py`

### Other components

- **DFT user**
- **Model hosting**
- **PySCF library**
- **GPU4PySCF library**
- **ASE library**
- **GauXC integration**

## Connections

- DFT user → PySCF workflow: runs calculation (evidence: `README.md`)
- DFT user → GPU4PySCF workflow: runs calculation (evidence: `README.md`)
- DFT user → ASE calculator: requests energy (evidence: `README.md`)
- PySCF workflow → Functional loader: loads functional (evidence: `skala/src/skala/pyscf/__init__.py`)
- GPU4PySCF workflow → Functional loader: loads functional (evidence: `skala/src/skala/gpu4pyscf/__init__.py`)
- Functional loader → Model hosting: downloads checkpoint (evidence: `skala/src/skala/functional/__init__.py`)
- Functional loader → Traced functional: loads artifact (evidence: `skala/src/skala/functional/__init__.py`)
- Functional loader → Traditional functionals: selects functional (evidence: `skala/src/skala/functional/__init__.py`)
- Traced functional → Feature schema: consumes features (evidence: `skala/src/skala/functional/base.py`)
- Traditional functionals → Feature schema: consumes features (evidence: `skala/src/skala/functional/traditional.py`)
- PySCF workflow → PySCF KS engine: constructs KS (evidence: `skala/src/skala/pyscf/__init__.py`)
- GPU4PySCF workflow → GPU KS engine: constructs KS (evidence: `skala/src/skala/gpu4pyscf/__init__.py`)
- ASE calculator → PySCF workflow: uses calculator (evidence: `skala/src/skala/ase/calculator.py`)
- PySCF KS engine → Numerical integration: configures integration (evidence: `skala/src/skala/pyscf/dft.py`)
- PySCF KS engine → PySCF gradients: provides gradients (evidence: `skala/src/skala/pyscf/dft.py`)
- PySCF KS engine → Grid management: configures grids (evidence: `skala/src/skala/pyscf/dft.py`)
- PySCF KS engine → DFT-D3 adapter: adds correction (evidence: `skala/src/skala/pyscf/dft.py`)
- Numerical integration → Model chunking: evaluates chunks (evidence: `skala/src/skala/pyscf/model_chunking.py`)
- Model chunking → AO evaluation: evaluates AO features (evidence: `skala/src/skala/pyscf/model_chunking.py`)
- Model chunking → Feature math: transforms features (evidence: `skala/src/skala/pyscf/model_chunking.py`)
- AO evaluation → Feature math: uses feature operators (evidence: `skala/src/skala/pyscf/ao_evaluation.py`)
- PySCF KS engine → Backend selection: selects backend (evidence: `skala/src/skala/pyscf/backend.py`)
- GPU KS engine → GPU gradients: provides gradients (evidence: `skala/src/skala/gpu4pyscf/dft.py`)
- GPU KS engine → Grid management: uses grid support (evidence: `skala/src/skala/gpu4pyscf/dft.py`)
- GPU KS engine → DFT-D3 adapter: adds correction (evidence: `skala/src/skala/gpu4pyscf/dft.py`)
- GPU KS engine → Numerical integration: uses integration (evidence: `skala/src/skala/gpu4pyscf/dft.py`)
- GPU KS engine → GPU4PySCF library: extends library (evidence: `README.md`)
- PySCF workflow → PySCF library: integrates with (evidence: `README.md`)
- ASE calculator → ASE library: implements adapter (evidence: `README.md`)
- Trainable Skala model → Feature schema: uses feature schema (evidence: `model/src/skala_model/model.py`)
- Trainable Skala model → Traced functional: implements functional base (evidence: `model/src/skala_model/model.py`)
- Trainable Skala model → Model layers: uses layers (evidence: `model/src/skala_model/model.py`)
- Trainable Skala model → Irrep utilities: uses irreps (evidence: `model/src/skala_model/model.py`)
- Trainable Skala model → Symmetric contraction: uses contraction (evidence: `model/src/skala_model/model.py`)
- GauXC exporter → PySCF workflow: references integration (evidence: `gauxc/src/skala_gauxc/export.py`)
- GauXC exporter → GauXC integration: exports for (evidence: `README.md`)
