Skip to content

API Reference

Complete reference for Kamayan's Python API. This documentation covers all public classes and functions available for configuring and running Kamayan simulations.

Core Module

kamayan

Kamayan: A flexible framework for astrophysical hydrodynamics simulations.

Kamayan provides both C++ and Python interfaces for running MHD simulations built on the Parthenon AMR framework. The Python interface offers code_units for configuring simulations and a CLI system for running them.

Key components
  • KamayanManager: Main simulation configuration and execution manager
  • kamayan_app: Decorator for creating CLI applications from simulations
  • code_units: Grid, Driver, Physics, Hydro, EOS configuration classes
Example

Basic simulation setup::

from kamayan import KamayanManager, process_units
from kamayan.code_units.Grid import UniformGrid

# Configure and run simulation
uc = process_units("my_sim", setup_params=setup_params)
km = KamayanManager("simulation", uc)
km.execute()

Using the CLI decorator::

from kamayan import kamayan_app

@kamayan_app(description="My simulation")
def my_simulation():
    # Configure your simulation
    return km

Version: 0.1.0

CLI Interface

kamayan.cli

Kamayan CLI interface providing the @kamayan_app decorator and simulation commands.

kamayan_app 

kamayan_app(
    name: Optional[str] = None,
    *,
    description: Optional[str] = None,
) -> Callable

Decorator to create a Kamayan simulation CLI.

Parameters:

Name Type Description Default
name Optional[str]

Optional name for the simulation

 None
description Optional[str]

Optional description for the CLI help

 None
Usage

@kamayan_app def my_simulation() -> KamayanManager: km = KamayanManager(...) # configure ... return km

if name == "main": my_simulation.app()

The decorated function can also be used directly

km = my_simulation()

Code Units

kamayan.code_units

Code units for configuring Kamayan simulations.

This module provides high-level Python classes for configuring various aspects of Kamayan simulations including grid setup, physics modules, equation of state, outputs, and runtime parameters.

Main classes
  • KamayanGrid: Mesh and boundary configuration
  • Driver: Time integration settings
  • KamayanPhysics: Physics module selection
  • Hydro: Hydrodynamics configuration
  • GammaEos: Ideal gas equation of state
  • KamayanOutputs: Output file configuration
  • KamayanParams: Runtime parameter management
Example

Basic configuration setup::

from kamayan.code_units import driver, physics
from kamayan.code_units.Grid import UniformGrid, outflow_box
from kamayan.code_units.Hydro import Hydro
from kamayan.code_units.eos import GammaEos

# Configure grid
grid = UniformGrid(nx1=128, nx2=128, nx3=1)
grid.boundary_conditions = outflow_box()

# Configure physics
phys = physics.KamayanPhysics()
phys.hydro = Hydro(reconstruction="plm")
phys.eos = GammaEos(gamma=1.4)

# Configure driver
drv = driver.Driver(tlim=0.2)

Simulation Manager

kamayan.kamayan_manager

Manager for a kamayan simulation.

KamayanManager

Manages the an instance of the kamayan simulation.

params cached property 
params: KamayanParams

Get parameters interface for setting overrides.

write_input 
write_input(file: None | Path = None)

Write out all the params owned by the unit data collection.

Format as a parthenon input file.

execute 
execute(*args: str)

Initialize the kamayan environment and execute the simulation.

Parameters:

Name Type Description Default
*args str

Additional arguments to forward to Parthenon (e.g., parthenon/time/nlim=100)

 ()

process_units 

process_units(
    name: str,
    setup_params: SetupInterface | None = None,
    initialize: InitializeInterface | None = None,
    pgen: ProblemGeneratorInterface | None = None,
) -> pk.UnitCollection

Build a default UnitCollection with a user provided KamayanUnit.

Parameters:

Name Type Description Default
name str

Name for user generated KamayanUnit

 required
setup_params SetupInterface | None

hook into parameter setup

 None
initialize InitializeInterface | None

hook into package initialization

 None
pgen ProblemGeneratorInterface | None

problem generator

 None