Skip to content

Declarative mechanism files compiled into the solver interface #16

Closed

Description

@rmrsk

Problem

A mechanism is a Python module that incept1d.mechanism.load_mechanism execs, and it must expose the solver's own matrices: get_R, get_V, get_B, get_C, get_kappa, the row selectors get_Pi_e / get_Pi_plus / get_Pi_minus and the yields get_gamma_plus / get_gamma_plus_with / get_gamma_Psi. This is fully general (the relativistic feedback model fits it unchanged), but as the interface users write against it has costs:

  • Derivable inputs are asked for. The row selectors Π follow from each species' charge and drift direction; the user builds them by hand.
  • Solver vocabulary, not physics. Writing get_B / get_C correctly needs the augmented-matrix layout (theory/augmented.rst). Shapes are loosely checked and no units are declared.
  • Air-specific leaks. get_gamma_plus_with(gamma0, gamma1, eref, beta) hard-codes one emission model into the generic interface.
  • Configuration plumbing. config.py injects variables into the module's globals before it is exec'd (pre_exec_vars / post_exec_init / mechanism_params). It works, but it is the hardest part to explain.

Proposal

A declarative mechanism file (JSON or YAML) compiled into the existing interface, which stays as the low-level escape hatch:

  • Species: name, charge, transport (mobility / drift velocity as a table vs E/N or a small set of expression forms).
  • Reactions as strings, reusing incept1d.reactions ("e + N2 -> 2e + N2+"), each with a rate reference: constant, table vs E/N, or a standard fit.
  • Photon groups: absorption, source reactions, direction (both / forward / backward, as PHOTON_DIRECTIONS), coupling products.
  • Electrode yields: ion and photon secondary emission, as constants or a named model with parameters.
  • The compiler derives Π, assembles R, V, B, C, κ, validates shapes, species names and units, and produces a Mechanism the solvers use unchanged.

Python mechanism modules remain supported for models that do not fit the declarative form (e.g. mechanisms/air/rfd/).

Open questions

  • chombo-discharge compatibility. incept1d chombo already exports to chombo-discharge, which has its own JSON plasma-chemistry input. Reading that format (or a subset) would let one file drive both codes; check how much of it, photons especially, maps onto the model before inventing a new schema.
  • Rate forms. Which fixed forms cover the shipped mechanisms (Pancheshnyi, 2body, Paschen) without turning the format into a programming language.
  • Configurations. How the JSON configuration files (reaction multipliers, yield overrides, gas composition) apply to a declarative mechanism, ideally as plain overrides of its fields.

Acceptance

  • Equivalence. The Pancheshnyi, 2body and Paschen mechanisms written declaratively reproduce their Python versions' A_aug to round-off and their inception curves unchanged.
  • Docs. The Configuration chapter documents the schema; the Python interface is documented as the advanced route.
  • Tests. Malformed files (unknown species, unbalanced charge, bad shapes, unknown keys) are rejected with clear errors.

Activity

  1. self-assigned this
    on Oct 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions