kore

kore is a portable Schrödinger-Poisson pseudo-spectral kernel for research workloads, with one validated Rust core exposed through Rust, Python, and C surfaces.

For the full technical manual, see docs/index.md.

Overview

kore packages a reusable numerical kernel for Schrödinger-Poisson simulations around a Rust implementation that also supports Python and C integration. It is aimed at researchers and scientific developers who want one computational core that can move cleanly between prototyping, scripting, and systems integration.

Why kore

Research code often starts in notebooks, grows into scripts, and eventually needs a stable systems boundary. kore is designed to keep that path straightforward: one kernel, portable interfaces, checkpoint/resume support, and a layout that serves both exploratory and production-adjacent research workflows.

Features

• Portable Rust core for Schrödinger-Poisson research workloads
• pykore Python bindings with NumPy complex128 in-place stepping
• Stable C ABI with generated header for non-Rust environments
• Optional HDF5 checkpoint support for resumable simulation runs
• CI-verified build, test, lint, header drift, and packaging workflows

Installation

Installation depends on which surface you want to use.

• Rust users can build the crate with Cargo
• Python users can install the bindings with pip install pykore
• C and mixed-language users can link against the generated C ABI artifacts

The core crate builds without HDF5 by default. Checkpointing is available through the optional checkpoint-hdf5 feature.

Quick Start

The fastest way to get started is to choose the surface that matches your workflow.

pip install pykore

import numpy as np
import pykore

grid = pykore.Grid((64, 64, 64), (1.0, 1.0, 1.0))
config = pykore.Config(dt=0.01, poisson_scale=1.0)
state = pykore.State(np.zeros((64, 64, 64), dtype=np.complex128))
kernel = pykore.Kernel(grid, config)
print(kernel.diagnostics(state))

Python

The Python surface is published as pykore on PyPI and is designed for NumPy-first scientific workflows. It exposes Grid, Config, State, Kernel, Diagnostics, and DiagnosticsSummary while keeping the compute path in Rust.

C ABI

The C ABI provides a stable interoperability layer for consumers outside Rust. The generated header is checked in as include/kore.h, and the ABI is verified with strict C11 smoke builds and header drift checks.

HDF5 Checkpoints

kore includes optional HDF5 checkpoint support for workflows that need to persist and resume simulation state.

cargo test --features checkpoint-hdf5

The checkpoint layer is versioned, shared across surfaces, and designed to reconstruct runs from stored grid/state data.

Paper

The current project paper is available in this repository as paper.pdf.

Status

kore is under active development and currently includes:

• Rust CPU kernel
• C ABI
• pykore Python bindings
• optional HDF5 checkpointing
• PyPI publication workflow and package release path

License

Licensed under either MIT or Apache-2.0. See LICENSE-MIT and LICENSE-APACHE.