Skip to content

CLAUDE.md

Latest commit

 

History

History
84 lines (58 loc) · 3.25 KB

CLAUDE.md

File metadata and controls

84 lines (58 loc) · 3.25 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build and Test Commands

# Configure (out-of-source build)
cmake -B build -S .

# Build
cmake --build build -j$(nproc)

# Run all tests
cd build && ctest --output-on-failure

# Run a single test
cd build && ctest -R test_Dataset --output-on-failure

# Build and run a single test executable directly
cmake --build build --target test_Dataset
./build/tests/test_Dataset

# Parallel IO (requires MPI)
cmake -B build-mpi -S . -DUSE_MPI=ON -DENABLE_PARALLEL_IO=ON
cmake --build build-mpi -j$(nproc)

# Parallel computing only (MPI topology/halo, no parallel IO)
cmake -B build-mpi -S . -DUSE_MPI=ON
cmake --build build-mpi -j$(nproc)

Dependencies

  • Fortran compiler (gfortran), C compiler
  • CMake >= 3.18
  • NetCDF-Fortran (found via pkg-config: netcdf-fortran)
  • HDF5 with Fortran bindings
  • C backend uses uthash (header uthash.h in src/c_backend/)
  • Parallel IO (optional): MPI, parallel HDF5
  • Kokkos (mandatory): GPU/CPU backend, requires Kokkos CMake package (see src/kokkos/CLAUDE.md)

Environment

  • Use Spack environment unistate — mixing system and Spack HDF5/NetCDF causes ABI crashes
  • CMake detects Spack env via $SPACK_ENV to avoid adding /usr/include
  • Module files (.mod) go to ${CMAKE_BINARY_DIR}/include

Architecture

Modern Fortran (2003+) library for managing simulation state, inspired by xarray. Uses OOP with type extension, polymorphic dispatch, and iso_c_binding.

Layers (see subdirectory CLAUDE.md for details)

  1. Precision → C Backend → Core Types (src/core/) → Variable → Registry (src/registry/) → Parallel (src/parallel/) → Component → IO (src/io/)
  2. Kokkos (src/kokkos/) — C++ core (buffer management, kernel dispatch) + Fortran interface (iso_c_binding). Always enabled.
  3. Each src/*/CLAUDE.md has gotchas and conventions specific to that layer

Key Design Decisions

  • include/unistate_layout.h defines Kokkos-compatible layout macros
  • Module naming convention: type Foo lives in module Foo_Mod
  • Fortran source list order in CMakeLists.txt reflects dependency chain — modules must compile before dependents
  • Data_Buffer is polymorphic — use select type for dispatch, never assume concrete type
  • Parallel layer (src/parallel/) provides topology, halo exchange, and MPI communication — most files compile unconditionally; only Comm_Backend_Mod requires USE_MPI=ON
  • USE_MPI enables parallel computing (topology/halo); ENABLE_PARALLEL_IO enables parallel HDF5/NetCDF I/O (implies USE_MPI)
  • Kokkos is always enabled — C++ templates handle view wrappers (ranks 1–8, managed/unmanaged); Fortran code uses Kokkos for buffer management and kernel dispatch

Testing Pattern

Tests are standalone Fortran programs (not frameworks). Each test:

  • uses the module under test
  • Creates objects, exercises functionality, checks values with if assertions
  • Prints pass/fail messages
  • Calls destroy methods for cleanup

Examples

examples/ contains usage examples, built automatically via CMake:

  • ex1_su2_style.f90 — SU2-style static field registration and I/O
  • ex2_dynamic.f90 — Dynamic field allocation pattern