docs: add repository readme changelog and paper

Author: edengilbertus

CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## v0.2.1
+- Published `pykore` 0.2.1 for Python users.
+- `pip install pykore` now provides the validated Schrödinger-Poisson solver bindings directly.
+- Added a stable package landing page and release path for wheel-based distribution.
+
+## v0.2.0-dev
+- Added optional HDF5 checkpoint support for saving and resuming simulation runs.
+- Introduced a shared checkpoint format for reproducible grid/state persistence.
+- Made `kore` usable in longer-running research workflows that need checkpoint/restart behavior.
+
+## v0.1.0-dev
+- Added the initial Rust CPU kernel for Schrödinger-Poisson workloads.
+- Added a stable C ABI for integration outside Rust.
+- Added `pykore` Python bindings for NumPy-based simulation workflows.

README.md

@@ -0,0 +1,84 @@
+# 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.
+
+## 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.
+
+```bash
+pip install pykore
+```
+
+```python
+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.
+
+```bash
+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`](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`.