keppy

keppy is a modern Python interface for the KEPLER stellar evolution code. It converts human-readable TOML configuration files into the legacy punch-card input format that KEPLER expects, and provides tools to manage chemical compositions and generate initial stellar structures via the Lane-Emden polytropic solver.

Installation

You will need to have read-access to the repo. Ask for this after making a sourcehut account.

git clone git@git.sr.ht:~rileythai/keppy
cd keppy
uv sync

Fortran extensions (the Lane-Emden solver and the convection data loader) are compiled automatically on first import. You will need a Fortran compiler (gfortran) and meson available on your system.

Environment

KEPLER_DATA must point to the KEPLER auxiliary data directory when using composition presets:

export KEPLER_DATA=~/projects/kepler/local_data

This is only required when [chemistry] preset = "..." is used. Custom compositions ([chemistry] custom = {...}) work without it.

Quick start

Command line

keppy star.toml starg

Python

from keppy.main import load_config, kepgen

config = load_config("star.toml")
kepgen("star.toml", "starg")

Configuration file format

A keppy configuration file is a TOML document with five top-level sections:

[model]
mass        = 20.0       # initial mass in M_sun
metallicity = 0.014      # metal fraction Z (solar ≈ 0.014)
rotation    = 0.0        # rotation rate parameter

[chemistry]
preset   = "as09"        # Asplund+2009 solar composition
scale_to_Z = true        # rescale abundances to match metallicity

[chemistry.custom]       # maybe instead you want a custom composition?
h1 = 0.75
h2 = 5e-6
he3 = 7e-7
he4 = 0.24


[grid]
ngrid = 500              # initial number of zones

[parameters]
dtmax = 3e12             # maximum timestep (seconds)

[plot]
plot1 = "abundances"

See the Configuration API for all available fields and their defaults.

Architecture

Module	Purpose
`keppy.main`	CLI entrypoint, `load_config`, `kepgen`
`keppy.models`	Pydantic configuration models
`keppy.converter`	Punch-card generation pipeline
`keppy.schemas`	Punch-card line format definitions
`keppy.chemistry`	Nuclear isotope and composition management
`keppy.laneemden`	Lane-Emden polytropic stellar structure solver
`keppy.data`	KEPLER output analysis — pending refactor