feat(python): added robust python bindings covering the entire codebase

2025-07-23 16:26:30 -04:00
parent 6a22cb65b8
commit f20bffc411
134 changed files with 2202 additions and 170 deletions
--- a/src/python/engine/trampoline/meson.build
+++ b/src/python/engine/trampoline/meson.build
@@ -0,0 +1,21 @@
+gf_engine_trampoline_sources = files('py_engine.cpp')
+
+gf_engine_trapoline_dependencies = [
+    gridfire_dep,
+    pybind11_dep,
+    python3_dep,
+]
+
+gf_engine_trampoline_lib = static_library(
+    'engine_trampolines',
+    gf_engine_trampoline_sources,
+    include_directories: include_directories('.'),
+    dependencies: gf_engine_trapoline_dependencies,
+    install: false,
+)
+
+gr_engine_trampoline_dep = declare_dependency(
+    link_with: gf_engine_trampoline_lib,
+    include_directories: ('.'),
+    dependencies: gf_engine_trapoline_dependencies,
+)
--- a/src/python/engine/trampoline/py_engine.cpp
+++ b/src/python/engine/trampoline/py_engine.cpp
@@ -0,0 +1,219 @@
+#include "py_engine.h"
+
+#include "gridfire/engine/engine.h"
+
+#include <pybind11/pybind11.h>
+#include <pybind11/stl.h>
+#include <pybind11/functional.h> // Needed for std::function
+
+#include <expected>
+#include <unordered_map>
+#include <vector>
+
+
+namespace py = pybind11;
+
+const std::vector<fourdst::atomic::Species>& PyEngine::getNetworkSpecies() const {
+    PYBIND11_OVERRIDE_PURE(
+        std::vector<fourdst::atomic::Species>,
+        gridfire::Engine,  /* Base class */
+        getNetworkSpecies
+    );
+}
+
+std::expected<gridfire::StepDerivatives<double>, gridfire::expectations::StaleEngineError> PyEngine::calculateRHSAndEnergy(const std::vector<double> &Y, double T9, double rho) const {
+    PYBIND11_OVERRIDE_PURE(
+        PYBIND11_TYPE(std::expected<gridfire::StepDerivatives<double>, gridfire::expectations::StaleEngineError>),
+        gridfire::Engine,
+        calculateRHSAndEnergy,
+        Y, T9, rho
+    );
+}
+
+///////////////////////////////////////
+/// PyDynamicEngine Implementation ///
+/////////////////////////////////////
+
+const std::vector<fourdst::atomic::Species>& PyDynamicEngine::getNetworkSpecies() const {
+    PYBIND11_OVERRIDE_PURE(
+        std::vector<fourdst::atomic::Species>,
+        gridfire::DynamicEngine,  /* Base class */
+        getNetworkSpecies
+    );
+}
+std::expected<gridfire::StepDerivatives<double>, gridfire::expectations::StaleEngineError> PyDynamicEngine::calculateRHSAndEnergy(const std::vector<double> &Y, double T9, double rho) const {
+    PYBIND11_OVERRIDE_PURE(
+        PYBIND11_TYPE(std::expected<gridfire::StepDerivatives<double>, gridfire::expectations::StaleEngineError>),
+        gridfire::Engine,
+        calculateRHSAndEnergy,
+        Y, T9, rho
+    );
+}
+
+void PyDynamicEngine::generateJacobianMatrix(const std::vector<double> &Y_dynamic, double T9, double rho) const {
+    PYBIND11_OVERRIDE_PURE(
+        void,
+        gridfire::DynamicEngine,
+        generateJacobianMatrix,
+        Y_dynamic, T9, rho
+    );
+}
+
+void PyDynamicEngine::generateJacobianMatrix(const std::vector<double> &Y_dynamic, double T9, double rho, const gridfire::SparsityPattern &sparsityPattern) const {
+    PYBIND11_OVERRIDE_PURE(
+        void,
+        gridfire::DynamicEngine,
+        generateJacobianMatrix,
+        Y_dynamic, T9, rho, sparsityPattern
+    );
+}
+
+double PyDynamicEngine::getJacobianMatrixEntry(int i, int j) const {
+    PYBIND11_OVERRIDE_PURE(
+        double,
+        gridfire::DynamicEngine,
+        getJacobianMatrixEntry,
+        i, j
+    );
+}
+
+void PyDynamicEngine::generateStoichiometryMatrix() {
+    PYBIND11_OVERRIDE_PURE(
+        void,
+        gridfire::DynamicEngine,
+        generateStoichiometryMatrix
+    );
+}
+
+int PyDynamicEngine::getStoichiometryMatrixEntry(int speciesIndex, int reactionIndex) const {
+    PYBIND11_OVERRIDE_PURE(
+        int,
+        gridfire::DynamicEngine,
+        getStoichiometryMatrixEntry,
+        speciesIndex, reactionIndex
+    );
+}
+
+double PyDynamicEngine::calculateMolarReactionFlow(const gridfire::reaction::Reaction &reaction, const std::vector<double> &Y, double T9, double rho) const {
+    PYBIND11_OVERRIDE_PURE(
+        double,
+        gridfire::DynamicEngine,
+        calculateMolarReactionFlow,
+        reaction, Y, T9, rho
+    );
+}
+
+const gridfire::reaction::LogicalReactionSet& PyDynamicEngine::getNetworkReactions() const {
+    PYBIND11_OVERRIDE_PURE(
+        const gridfire::reaction::LogicalReactionSet&,
+        gridfire::DynamicEngine,
+        getNetworkReactions
+    );
+}
+
+void PyDynamicEngine::setNetworkReactions(const gridfire::reaction::LogicalReactionSet& reactions) {
+    PYBIND11_OVERRIDE_PURE(
+        void,
+        gridfire::DynamicEngine,
+        setNetworkReactions,
+        reactions
+    );
+}
+
+std::expected<std::unordered_map<fourdst::atomic::Species, double>, gridfire::expectations::StaleEngineError> PyDynamicEngine::getSpeciesTimescales(const std::vector<double> &Y, double T9, double rho) const {
+    PYBIND11_OVERRIDE_PURE(
+        PYBIND11_TYPE(std::expected<std::unordered_map<fourdst::atomic::Species, double>, gridfire::expectations::StaleEngineError>),
+        gridfire::DynamicEngine,
+        getSpeciesTimescales,
+        Y, T9, rho
+    );
+}
+
+std::expected<std::unordered_map<fourdst::atomic::Species, double>, gridfire::expectations::StaleEngineError> PyDynamicEngine::getSpeciesDestructionTimescales(const std::vector<double> &Y, double T9, double rho) const {
+    PYBIND11_OVERRIDE_PURE(
+        PYBIND11_TYPE(std::expected<std::unordered_map<fourdst::atomic::Species, double>, gridfire::expectations::StaleEngineError>),
+        gridfire::DynamicEngine,
+        getSpeciesDestructionTimescales,
+        Y, T9, rho
+    );
+}
+
+fourdst::composition::Composition PyDynamicEngine::update(const gridfire::NetIn &netIn) {
+    PYBIND11_OVERRIDE_PURE(
+        fourdst::composition::Composition,
+        gridfire::DynamicEngine,
+        update,
+        netIn
+    );
+}
+
+bool PyDynamicEngine::isStale(const gridfire::NetIn &netIn) {
+    PYBIND11_OVERRIDE_PURE(
+        bool,
+        gridfire::DynamicEngine,
+        isStale,
+        netIn
+    );
+}
+
+void PyDynamicEngine::setScreeningModel(gridfire::screening::ScreeningType model) {
+    PYBIND11_OVERRIDE_PURE(
+        void,
+        gridfire::DynamicEngine,
+        setScreeningModel,
+        model
+    );
+}
+
+gridfire::screening::ScreeningType PyDynamicEngine::getScreeningModel() const {
+    PYBIND11_OVERRIDE_PURE(
+        gridfire::screening::ScreeningType,
+        gridfire::DynamicEngine,
+        getScreeningModel
+    );
+}
+
+int PyDynamicEngine::getSpeciesIndex(const fourdst::atomic::Species &species) const {
+    PYBIND11_OVERRIDE_PURE(
+        int,
+        gridfire::DynamicEngine,
+        getSpeciesIndex,
+        species
+    );
+}
+
+std::vector<double> PyDynamicEngine::mapNetInToMolarAbundanceVector(const gridfire::NetIn &netIn) const {
+    PYBIND11_OVERRIDE_PURE(
+        std::vector<double>,
+        gridfire::DynamicEngine,
+        mapNetInToMolarAbundanceVector,
+        netIn
+    );
+}
+
+gridfire::PrimingReport PyDynamicEngine::primeEngine(const gridfire::NetIn &netIn) {
+    PYBIND11_OVERRIDE_PURE(
+        gridfire::PrimingReport,
+        gridfire::DynamicEngine,
+        primeEngine,
+        netIn
+    );
+}
+
+const gridfire::Engine& PyEngineView::getBaseEngine() const {
+    PYBIND11_OVERRIDE_PURE(
+        const gridfire::Engine&,
+        gridfire::EngineView<gridfire::Engine>,
+        getBaseEngine
+    );
+}
+
+const gridfire::DynamicEngine& PyDynamicEngineView::getBaseEngine() const {
+    PYBIND11_OVERRIDE_PURE(
+        const gridfire::DynamicEngine&,
+        gridfire::EngineView<gridfire::DynamicEngine>,
+        getBaseEngine
+    );
+}
+
+
--- a/src/python/engine/trampoline/py_engine.h
+++ b/src/python/engine/trampoline/py_engine.h
@@ -0,0 +1,52 @@
+#pragma once
+
+#include "gridfire/engine/engine.h"
+#include "gridfire/expectations/expected_engine.h"
+
+#include "fourdst/composition/atomicSpecies.h"
+
+#include <vector>
+#include <expected>
+
+
+class PyEngine final : public gridfire::Engine {
+public:
+    const std::vector<fourdst::atomic::Species>& getNetworkSpecies() const override;
+    std::expected<gridfire::StepDerivatives<double>,gridfire::expectations::StaleEngineError> calculateRHSAndEnergy(const std::vector<double> &Y, double T9, double rho) const override;
+};
+
+class PyDynamicEngine final : public gridfire::DynamicEngine {
+    const std::vector<fourdst::atomic::Species>& getNetworkSpecies() const override;
+    std::expected<gridfire::StepDerivatives<double>,gridfire::expectations::StaleEngineError> calculateRHSAndEnergy(const std::vector<double> &Y, double T9, double rho) const override;
+    void generateJacobianMatrix(const std::vector<double> &Y_dynamic, double T9, double rho) const override;
+    void generateJacobianMatrix(const std::vector<double> &Y_dynamic, double T9, double rho, const gridfire::SparsityPattern &sparsityPattern) const override;
+    double getJacobianMatrixEntry(int i, int j) const override;
+    void generateStoichiometryMatrix() override;
+    int getStoichiometryMatrixEntry(int speciesIndex, int reactionIndex) const override;
+    double calculateMolarReactionFlow(const gridfire::reaction::Reaction &reaction, const std::vector<double> &Y, double T9, double rho) const override;
+    const gridfire::reaction::LogicalReactionSet& getNetworkReactions() const override;
+    void setNetworkReactions(const gridfire::reaction::LogicalReactionSet& reactions) override;
+    std::expected<std::unordered_map<fourdst::atomic::Species, double>, gridfire::expectations::StaleEngineError> getSpeciesTimescales(const std::vector<double> &Y, double T9, double rho) const override;
+    std::expected<std::unordered_map<fourdst::atomic::Species, double>, gridfire::expectations::StaleEngineError> getSpeciesDestructionTimescales(const std::vector<double> &Y, double T9, double rho) const override;
+    fourdst::composition::Composition update(const gridfire::NetIn &netIn) override;
+    bool isStale(const gridfire::NetIn &netIn) override;
+    void setScreeningModel(gridfire::screening::ScreeningType model) override;
+    gridfire::screening::ScreeningType getScreeningModel() const override;
+    int getSpeciesIndex(const fourdst::atomic::Species &species) const override;
+    std::vector<double> mapNetInToMolarAbundanceVector(const gridfire::NetIn &netIn) const override;
+    gridfire::PrimingReport primeEngine(const gridfire::NetIn &netIn) override;
+    gridfire::BuildDepthType getDepth() const override {
+        throw std::logic_error("Network depth not supported by this engine.");
+    }
+    void rebuild(const fourdst::composition::Composition& comp, gridfire::BuildDepthType depth) override {
+        throw std::logic_error("Setting network depth not supported by this engine.");
+    }
+};
+
+class PyEngineView final : public gridfire::EngineView<gridfire::Engine> {
+    const gridfire::Engine& getBaseEngine() const override;
+};
+
+class PyDynamicEngineView final : public gridfire::EngineView<gridfire::DynamicEngine> {
+    const gridfire::DynamicEngine& getBaseEngine() const override;
+};