rscm 0.5.0

Rust Simple Climate Model - PyO3 Python bindings
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114

//! Python module registration and submodule wiring.
//!
//! This module defines the PyO3 module structure exposed to Python. It registers
//! the root `_lib` module and all submodules, setting up the correct `sys.modules`
//! paths for Python's import system.
//!
//! # Module Hierarchy
//!
//! The bindings are structured as follows:
//!
//! ```text
//! rscm._lib                    # Root module (this file)
//! ├── core                     # Core abstractions from rscm-core
//! │   ├── spatial              # Spatial grid types
//! │   └── state                # State value types
//! ├── components               # Generic components from rscm-components
//! ├── two_layer                # Two-layer model from rscm-two-layer
//! └── magicc                   # MAGICC components from rscm-magicc
//! ```
//!
//! # Implementation Details
//!
//! PyO3 submodules require explicit registration in Python's `sys.modules` dictionary
//! to enable `from rscm._lib.submodule import X` syntax. The `set_path` and
//! `set_submodule_path` helper functions handle this registration.
//!
//! Each submodule is defined in its respective crate:
//!
//! - `core` module: [`rscm_core::python::core`]
//! - `components` module: [`rscm_components::python::components`]
//! - `two_layer` module: [`rscm_two_layer::python::two_layer`]
//! - `magicc` module: [`rscm_magicc::python::magicc`]

use pyo3::prelude::*;
use pyo3::wrap_pymodule;
use rscm_calibrate::python::calibrate;
use rscm_components::python::components;
use rscm_core::python::core;
use rscm_magicc::python::magicc;
use rscm_two_layer::python::two_layer;
use std::ffi::CString;

/// Root Python module for RSCM bindings.
///
/// This function is called by PyO3 when the module is imported. It registers
/// all submodules and sets up the Python import paths.
#[pymodule]
#[pyo3(name = "_lib")]
fn rscm(m: &Bound<'_, PyModule>) -> PyResult<()> {
    m.add("__version__", env!("CARGO_PKG_VERSION"))?;
    m.add_wrapped(wrap_pymodule!(core))?;
    m.add_wrapped(wrap_pymodule!(components))?;
    m.add_wrapped(wrap_pymodule!(two_layer))?;
    m.add_wrapped(wrap_pymodule!(magicc))?;
    m.add_wrapped(wrap_pymodule!(calibrate))?;

    set_path(m, "rscm._lib.core", "core")?;
    set_path(m, "rscm._lib.components", "components")?;
    set_path(m, "rscm._lib.two_layer", "two_layer")?;
    set_path(m, "rscm._lib.magicc", "magicc")?;
    set_path(m, "rscm._lib.calibrate", "calibrate")?;
    set_submodule_path(m, "rscm._lib.core.spatial", "core", "spatial")?;
    set_submodule_path(m, "rscm._lib.core.state", "core", "state")?;

    Ok(())
}

/// Register a submodule in Python's `sys.modules` dictionary.
///
/// This enables `from rscm._lib.{module} import X` syntax by making the
/// submodule discoverable through Python's import machinery.
///
/// # Arguments
///
/// * `m` - The parent module bound to Python
/// * `path` - The full dotted path to register (e.g., "rscm._lib.core")
/// * `module` - The local module name (e.g., "core")
fn set_path(m: &Bound<'_, PyModule>, path: &str, module: &str) -> PyResult<()> {
    let code = CString::new(format!(
        "\
import sys
sys.modules['{path}'] = {module}
    "
    ))
    .unwrap();
    m.py().run(code.as_c_str(), None, Some(&m.dict()))
}

/// Register a nested submodule in Python's `sys.modules` dictionary.
///
/// Similar to [`set_path`], but for submodules nested within another submodule
/// (e.g., `rscm._lib.core.spatial`).
///
/// # Arguments
///
/// * `m` - The root module bound to Python
/// * `path` - The full dotted path to register (e.g., "rscm._lib.core.spatial")
/// * `parent` - The parent module name (e.g., "core")
/// * `submodule` - The submodule name (e.g., "spatial")
fn set_submodule_path(
    m: &Bound<'_, PyModule>,
    path: &str,
    parent: &str,
    submodule: &str,
) -> PyResult<()> {
    let code = CString::new(format!(
        "\
import sys
sys.modules['{path}'] = {parent}.{submodule}
    "
    ))
    .unwrap();
    m.py().run(code.as_c_str(), None, Some(&m.dict()))
}