feat(BindingAPI): exose necessary classes

bindings/python/src/stochastic/CMakeLists.txt

@@ -21,8 +21,17 @@
 add_geode_python_binding(
     NAME "py_stochastic"
     SOURCES
-#        "random_engine.cpp"
+        "sampling/mcmc/helpers/fracture_simulation_runner.hpp"
+        "sampling/mcmc/helpers/simulation_monitor.hpp"
+        "sampling/mcmc/helpers/simulation_printer.hpp"
+        "sampling/mcmc/helpers/simulation_runner.hpp"
+        "sampling/direct/double_sampler.hpp"
+        "sampling/random_engine.hpp"
+        "sampling/distributions.hpp"
         "stochastic.cpp"
     DEPENDENCIES
         ${PROJECT_NAME}::stochastic
+        OpenGeode::basic
+        OpenGeode::geometry
+        OpenGeode::model
 )

bindings/python/src/stochastic/sampling/direct/double_sampler.hpp

@@ -0,0 +1,67 @@
+/*
+ * Copyright (c) 2019 - 2025 Geode-solutions
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ */
+
+#include <geode/stochastic/sampling/direct/double_sampler.hpp>
+
+namespace geode
+{
+    void define_double_sampler( pybind11::module& module )
+    {
+        // Bind DistributionDescription
+        pybind11::class_< DoubleSampler::DistributionDescription >(
+            module, "DoubleDistributionDescription" )
+            .def( pybind11::init<>() )
+            .def_readwrite(
+                "name", &DoubleSampler::DistributionDescription::name )
+            .def_readwrite( "distribution_type",
+                &DoubleSampler::DistributionDescription::distribution_type )
+            .def_readwrite( "min_value",
+                &DoubleSampler::DistributionDescription::min_value )
+            .def_readwrite( "max_value",
+                &DoubleSampler::DistributionDescription::max_value )
+            .def_readwrite(
+                "mean", &DoubleSampler::DistributionDescription::mean )
+            .def_readwrite( "standard_deviation",
+                &DoubleSampler::DistributionDescription::standard_deviation )
+            .def( "string", &DoubleSampler::DistributionDescription::string,
+                "Return a detailed description of the Distribution law" )
+            .def( "__repr__",
+                []( const DoubleSampler::DistributionDescription& d ) {
+                    return "<DoubleDistributionDescription name=" + d.name
+                           + ">";
+                } );
+
+        // Bind Distribution variant
+        pybind11::class_< DoubleSampler::Distribution >(
+            module, "Distribution" );
+
+        // Bind DoubleSampler
+        pybind11::class_< DoubleSampler >( module, "DoubleSampler" )
+            .def_static( "create_distribution",
+                &DoubleSampler::create_distribution, pybind11::arg( "desc" ),
+                "Create a distribution from a description" )
+            .def_static( "sample", &DoubleSampler::sample,
+                pybind11::arg( "engine" ), pybind11::arg( "dist" ),
+                "Sample a value from a distribution using a RandomEngine" );
+    }
+} // namespace geode

bindings/python/src/stochastic/sampling/distributions.hpp

@@ -0,0 +1,92 @@
+/*
+ * Copyright (c) 2019 - 2025 Geode-solutions
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ */
+
+#include <geode/stochastic/sampling/distributions.hpp>
+
+namespace geode
+{
+
+    void define_distributions( pybind11::module& module )
+    {
+        // DistributionType
+        pybind11::class_< DistributionType >( module, "DistributionType" )
+            .def( pybind11::init<>() )
+            .def( pybind11::init< std::string >() )
+            .def( "get", &DistributionType::get )
+            .def( "matches", &DistributionType::operator== );
+
+        // UniformClosed<double>
+        pybind11::class_< UniformClosed< double > >( module, "UniformClosed" )
+            .def( pybind11::init<>() )
+            .def_readwrite( "min_value", &UniformClosed< double >::min_value )
+            .def_readwrite( "max_value", &UniformClosed< double >::max_value )
+            .def( "is_valid", &UniformClosed< double >::is_valid )
+            .def( "distribution_type_static",
+                &UniformClosed< double >::distribution_type_static )
+            .def( "distribution_type",
+                &UniformClosed< double >::distribution_type )
+            .def( "string", &UniformClosed< double >::string );
+
+        // UniformClosedOpen<double>
+        pybind11::class_< UniformClosedOpen< double > >(
+            module, "UniformClosedOpen" )
+            .def( pybind11::init<>() )
+            .def_readwrite(
+                "min_value", &UniformClosedOpen< double >::min_value )
+            .def_readwrite(
+                "max_value", &UniformClosedOpen< double >::max_value )
+            .def( "is_valid", &UniformClosedOpen< double >::is_valid )
+            .def( "distribution_type_static",
+                &UniformClosedOpen< double >::distribution_type_static )
+            .def( "distribution_type",
+                &UniformClosedOpen< double >::distribution_type )
+            .def( "string", &UniformClosedOpen< double >::string );
+
+        // Gaussian
+        pybind11::class_< Gaussian >( module, "Gaussian" )
+            .def( pybind11::init<>() )
+            .def_readwrite( "mean", &Gaussian::mean )
+            .def_readwrite(
+                "standard_deviation", &Gaussian::standard_deviation )
+            .def( "is_valid", &Gaussian::is_valid )
+            .def( "distribution_type_static",
+                &Gaussian::distribution_type_static )
+            .def( "distribution_type", &Gaussian::distribution_type )
+            .def( "string", &Gaussian::string );
+
+        // TruncatedGaussian
+        pybind11::class_< TruncatedGaussian >( module, "TruncatedGaussian" )
+            .def( pybind11::init<>() )
+            .def_readwrite( "mean", &TruncatedGaussian::mean )
+            .def_readwrite(
+                "standard_deviation", &TruncatedGaussian::standard_deviation )
+            .def_readwrite( "min_value", &TruncatedGaussian::min_value )
+            .def_readwrite( "max_value", &TruncatedGaussian::max_value )
+            .def( "is_valid", &TruncatedGaussian::is_valid )
+            .def( "distribution_type_static",
+                &TruncatedGaussian::distribution_type_static )
+            .def( "distribution_type", &TruncatedGaussian::distribution_type )
+            .def( "string", &TruncatedGaussian::string );
+    }
+
+} // namespace geode

bindings/python/src/stochastic/sampling/mcmc/helpers/fracture_simulation_runner.hpp

@@ -0,0 +1,84 @@
+/*
+ * Copyright (c) 2019 - 2025 Geode-solutions
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ */
+
+#include <geode/stochastic/sampling/mcmc/helpers/fracture_simulation_runner.hpp>
+
+namespace geode
+{
+    void define_fracture_simulation( pybind11::module& module )
+    {
+        using namespace geode;
+
+        pybind11::class_< FractureSetDescription >(
+            module, "FractureSetDescription" )
+            .def( pybind11::init<>() )
+            .def_readwrite( "name", &FractureSetDescription::name )
+            .def_readwrite( "length", &FractureSetDescription::length )
+            .def_readwrite( "azimuth", &FractureSetDescription::azimuth )
+            .def_readwrite( "p20", &FractureSetDescription::p20 )
+            .def_readwrite(
+                "minimal_spacing", &FractureSetDescription::minimal_spacing )
+            .def_readwrite(
+                "birth_ratio", &FractureSetDescription::birth_ratio )
+            .def_readwrite(
+                "death_ratio", &FractureSetDescription::death_ratio )
+            .def_readwrite(
+                "change_ratio", &FractureSetDescription::change_ratio )
+            .def( "string", &FractureSetDescription::string,
+                "Return a detailed description of the fracture set" )
+            .def( "__repr__", []( const FractureSetDescription& self ) {
+                return "<FractureSetDescription name='" + self.name + "'>";
+            } );
+
+        pybind11::class_< FractureSimulationRunner,
+            std::shared_ptr< FractureSimulationRunner > >(
+            module, "FractureSimulationRunner" )
+            .def( pybind11::init< const BoundingBox2D& >(),
+                pybind11::arg( "box" ) )
+            .def( "add_fracture_set_descriptor",
+                &FractureSimulationRunner::add_fracture_set_descriptor,
+                pybind11::arg( "descriptor" ),
+                "Add a fracture set configuration to the simulation." )
+            .def( "initialize", &FractureSimulationRunner::initialize,
+                "Initialize internal samplers, energy terms, and proposal "
+                "kernels." )
+            .def( "check_statistics",
+                &FractureSimulationRunner::check_statistics,
+                pybind11::arg( "statistic_monitoring" ),
+                "Check computed statistics after simulation." )
+            // Explicit overload bindings
+            //            .def( "run",
+            //                static_cast< const ObjectSets< OwnerSegment2D >& (
+            //                    FractureSimulationRunner::*) ( RandomEngine&,
+            //                    index_t ) >( &FractureSimulationRunner::run ),
+            //                pybind11::arg( "engine" ), pybind11::arg( "steps"
+            //                ), "Run simulation for a fixed number of steps." )
+            .def( "run",
+                static_cast< StatisticsMonitor ( FractureSimulationRunner::* )(
+                    RandomEngine&, const SimulationConfigurator& ) >(
+                    &FractureSimulationRunner::run ),
+                pybind11::arg( "engine" ), pybind11::arg( "config" ),
+                "Run the simulation and return statistics monitoring "
+                "results." );
+    }
+} // namespace geode

bindings/python/src/stochastic/sampling/mcmc/helpers/simulation_monitor.hpp

@@ -0,0 +1,51 @@
+/*
+ * Copyright (c) 2019 - 2025 Geode-solutions
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ */
+
+#include <geode/stochastic/sampling/mcmc/helpers/simulation_monitor.hpp>
+
+namespace geode
+{
+    void define_simulation_monitor( pybind11::module& module )
+    {
+        pybind11::class_< geode::StatisticsMonitor >(
+            module, "StatisticsMonitor" )
+            .def( pybind11::init< geode::index_t >(),
+                pybind11::arg( "nb_energy_terms" ),
+                "Create a StatisticsMonitor for a given number of energy "
+                "terms" )
+            .def( "add_realization", &geode::StatisticsMonitor::add_realization,
+                pybind11::arg( "values" ),
+                "Add a realization (vector of doubles) to update statistics" )
+            .def( "statiscal_count", &geode::StatisticsMonitor::statiscal_count,
+                "Return the number of realizations added" )
+            .def_property_readonly( "means", &geode::StatisticsMonitor::means,
+                "Return the computed mean values for each energy term" )
+            .def_property_readonly( "variances",
+                &geode::StatisticsMonitor::variances,
+                "Return the computed variances for each energy term" )
+            .def( "__repr__", []( const geode::StatisticsMonitor& self ) {
+                return "<StatisticsMonitor count="
+                       + std::to_string( self.statiscal_count() ) + ">";
+            } );
+    }
+} // namespace geode