Skip to content

AGENTS.md

Latest commit

 

History

History
104 lines (83 loc) · 3.63 KB

AGENTS.md

File metadata and controls

104 lines (83 loc) · 3.63 KB

AGENTS.md

This file provides guidance to AI coding agents (e.g., GitHub Copilot, Cursor, OpenAI Codex) working within the Skala repository. Follow these conventions to produce consistent, high-quality contributions.

Repository overview

Skala is a neural network-based exchange-correlation (XC) functional for density functional theory (DFT). The codebase includes:

Path Description
src/skala/ Core Python package (model, PySCF/ASE integrations, utilities)
tests/ Pytest test suite
docs/ Sphinx documentation (RST + Jupyter notebooks via myst-nb)
examples/ Usage examples (Python scripts and C++ integrations)
third_party/gauxc/ Vendored GauXC library with Skala support
.github/workflows/ CI workflows (test, docs)

Development environment

  1. Python version: ≥3.10 (target 3.11 for tooling).
  2. Environment setup (conda recommended): 
    mamba env create -f environment.yml
mamba activate skala
pip install -e .
  3. Pre-commit hooks (required before committing): 
    pre-commit install
pre-commit run --all-files

Code style & linting

  • Formatter/linter: Ruff (ruff format, ruff check --fix --select I).
  • Type checking: mypy with --ignore-missing-imports.
  • Line length: 100 characters (Black-compatible).
  • Imports sorted via Ruff's isort rules.
  • Exclude third_party/ and tests/ from mypy; exclude third_party/ from Ruff.

When editing code:

  • Run ruff format <file> and ruff check --fix <file> before committing.
  • Add type hints to new public functions and classes.
  • Use Google-style docstrings with Args:, Returns:, Raises: sections.

Testing

  • Framework: pytest with pytest-cov.
  • Run tests: 
    pytest tests/ -v --cov=skala
  • Keep test files in tests/ with test_ prefix.
  • Use fixtures for expensive setup (molecule construction, model loading).
  • Prefer fast unit tests; integration tests that run DFT should be marked or placed separately.

Documentation

  • Engine: Sphinx with myst-nb (executes notebooks during build).
  • Build locally: 
    sphinx-build -b html docs docs/_build/html
  • Notebooks in docs/ should be executable with a 5-minute timeout.
  • Use reStructuredText for standalone pages; Jupyter notebooks for tutorials.

Pull request guidelines

  1. Create a feature branch from main.
  2. Ensure pre-commit hooks pass.
  3. Add or update tests for new functionality.
  4. Update documentation if public API changes.
  5. Keep commits atomic; write clear commit messages.
  6. CI must pass (tests, linting, docs build).

Architecture notes

  • Functional implementation (src/skala/functional/): Defines the Skala model layers, density features, and enhancement-factor network. The pre-trained weights are loaded via Hugging Face Hub.
  • PySCF integration (src/skala/pyscf/): Custom numint module and SkalaKS class hook the model into PySCF's DFT machinery.
  • ASE calculator (src/skala/ase/): Provides an ASE-compatible calculator for energy/force evaluations and geometry optimizations.
  • GauXC add-on (third_party/gauxc/): C++ library enabling Skala in compiled DFT codes; uses LibTorch for inference.

Common tasks

Task Command
Format code ruff format src/ tests/
Lint code ruff check --fix src/ tests/
Run tests pytest tests/ -v
Build docs sphinx-build -b html docs docs/_build/html
Type check mypy src/skala

Contact