SCOPE-RTM 0.1.0__tar.gz

scope_rtm-0.1.0/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: SCOPE-RTM
+Version: 0.1.0
+Summary: PyTorch reimplementation of the SCOPE radiative transfer model.
+Author-email: Marc Yin <marc.yin@example.com>
+License-Expression: GPL-3.0-only
+Keywords: scope,radiative-transfer,remote-sensing,pytorch,fluorescence,thermal
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: torch>=2.2
+Requires-Dist: numpy>=1.26
+Requires-Dist: scipy>=1.11
+Requires-Dist: xarray>=2024.1
+Requires-Dist: rioxarray>=0.15
+Requires-Dist: pandas>=2.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8.1; extra == "dev"
+Requires-Dist: pytest-cov>=4.1; extra == "dev"
+Requires-Dist: prosail>=2.0; extra == "dev"
+Requires-Dist: rich>=13.7; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Requires-Dist: mkdocs-mermaid2-plugin>=1.2; extra == "docs"
+Provides-Extra: release
+Requires-Dist: build>=1.2; extra == "release"
+Requires-Dist: twine>=5.1; extra == "release"
+
+# SCOPE
+
+PyTorch-first implementation of the SCOPE canopy radiative transfer model for reflectance, fluorescence, thermal radiance, and coupled energy-balance workflows.
+
+## What It Is
+
+`scope` is designed for users who need:
+
+- asset-backed SCOPE physics in Python
+- batched ROI/time execution on `xarray` datasets
+- differentiable model components in PyTorch
+- reproducible MATLAB parity checks in CI and local development
+
+The current implementation supports:
+
+- leaf optics through FLUSPECT
+- canopy reflectance through 4SAIL-based transport
+- layered fluorescence and thermal radiative transfer
+- leaf biochemistry and coupled energy balance
+- directional and vertical-profile outputs on the homogeneous canopy path
+- ROI/time workflows with `xarray` input and output assembly
+
+## Install
+
+Published package name:
+
+```bash
+python -m pip install SCOPE-RTM
+```
+
+Import name:
+
+```python
+import scope
+```
+
+### 1. Clone the repository
+
+```bash
+git clone <your-repo-url> scope
+cd scope
+```
+
+### 2. Fetch the pinned upstream SCOPE assets
+
+```bash
+python scripts/fetch_upstream_scope.py
+```
+
+If you installed the package in an environment already, the same helper is available as:
+
+```bash
+scope-fetch-upstream
+```
+
+### 3. Create an environment and install
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+```
+
+### 4. Verify the install
+
+```bash
+PYTHONPATH=src python examples/basic_scene_reflectance.py
+PYTHONPATH=src python -m pytest -q tests/test_scope_benchmark_parity.py tests/test_scope_timeseries_benchmark_parity.py
+```
+
+## 5-Minute Quickstart
+
+### Minimal scene reflectance run
+
+```bash
+PYTHONPATH=src python examples/basic_scene_reflectance.py
+```
+
+Expected output:
+
+```json
+{
+  "product": "reflectance",
+  "dims": {"y": 1, "x": 1, "time": 1, "wavelength": 2001},
+  "rsot_650nm": 0.047138178221010914,
+  "rsot_865nm": 0.4100649627325952,
+  "rsot_1600nm": 0.26994893328935227
+}
+```
+
+### High-level workflow run
+
+```bash
+PYTHONPATH=src python examples/scope_workflow_demo.py
+```
+
+Expected output:
+
+```json
+{
+  "product": "scope_workflow",
+  "components": [
+    "reflectance",
+    "reflectance_directional",
+    "reflectance_profile",
+    "fluorescence",
+    "fluorescence_directional",
+    "fluorescence_profile"
+  ],
+  "rsot_650nm_t0": 0.04522854188089004,
+  "LoF_peak_t0": 1.985767010834904e-05,
+  "LoF_peak_wavelength_t0": 744.0
+}
+```
+
+## Main Entry Points
+
+For most users, the preferred entry points are:
+
+- [`ScopeGridRunner.run_scope_dataset(...)`](src/scope/runners/grid.py)
+  High-level reflectance/fluorescence/thermal workflow dispatch from prepared `xarray` inputs.
+- [`prepare_scope_input_dataset(...)`](src/scope/io/prepare.py)
+  Build a runner-ready dataset from weather, observation, and Sentinel-2 bio inputs.
+- [`write_netcdf_dataset(...)`](src/scope/io/export.py)
+  Persist prepared or simulated outputs to NetCDF with safe backend selection and compression handling.
+
+For direct lower-level use:
+
+- [`FluspectModel`](src/scope/spectral/fluspect.py)
+- [`CanopyReflectanceModel`](src/scope/canopy/reflectance.py)
+- [`CanopyFluorescenceModel`](src/scope/canopy/fluorescence.py)
+- [`CanopyThermalRadianceModel`](src/scope/canopy/thermal.py)
+- [`CanopyEnergyBalanceModel`](src/scope/energy/balance.py)
+
+## Documentation Map
+
+- [Installation Guide](docs/installation.md)
+- [Quickstart](docs/quickstart.md)
+- [Model Mechanics](docs/model-mechanics.md)
+- [Input / Output Reference](docs/input-output-reference.md)
+- [Examples](docs/examples.md)
+- [Production Notes](docs/production-notes.md)
+- [Benchmark Policy](docs/benchmark-policy.md)
+
+Build the docs locally with:
+
+```bash
+python -m pip install -e ".[docs]"
+mkdocs build --strict
+```
+
+## Production Notes
+
+- Asset-backed constructors such as `from_scope_assets(...)` require an upstream SCOPE checkout. The recommended path is `scope-fetch-upstream`.
+- The default CI suite runs parity tests in live-or-pregenerated mode. On machines without MATLAB, the tests compare against checked-in MATLAB fixtures.
+- The self-hosted GPU and live-MATLAB lanes remain optional operational lanes; see [docs/benchmark-policy.md](docs/benchmark-policy.md).
+- Documentation can be built locally with `mkdocs build --strict` and is deployed by the dedicated GitHub Pages workflow.
+- Distribution artifacts can be built locally with `python -m build` and validated with `python -m twine check dist/*`.
+
+## Testing
+
+Run the default suite with:
+
+```bash
+PYTHONPATH=src python -m pytest -q
+```
+
+The strongest automated checks currently include:
+
+- kernel parity and execution-mode regression tests
+- ROI/time runner consistency tests
+- committed scene and time-series benchmark summary regression tests
+- live-or-pregenerated MATLAB parity tests for the single-scene and time-series benchmark gates
+
+## Release Workflows
+
+- `.github/workflows/release.yml`
+  Builds `sdist` and wheel artifacts for `SCOPE-RTM`, validates them with `twine check`, and auto-publishes to PyPI on version tags. Manual dispatch still supports TestPyPI or PyPI.
+- `.github/workflows/docs.yml`
+  Builds the MkDocs site and deploys it to GitHub Pages.

scope_rtm-0.1.0/README.md

@@ -0,0 +1,181 @@
+# SCOPE
+
+PyTorch-first implementation of the SCOPE canopy radiative transfer model for reflectance, fluorescence, thermal radiance, and coupled energy-balance workflows.
+
+## What It Is
+
+`scope` is designed for users who need:
+
+- asset-backed SCOPE physics in Python
+- batched ROI/time execution on `xarray` datasets
+- differentiable model components in PyTorch
+- reproducible MATLAB parity checks in CI and local development
+
+The current implementation supports:
+
+- leaf optics through FLUSPECT
+- canopy reflectance through 4SAIL-based transport
+- layered fluorescence and thermal radiative transfer
+- leaf biochemistry and coupled energy balance
+- directional and vertical-profile outputs on the homogeneous canopy path
+- ROI/time workflows with `xarray` input and output assembly
+
+## Install
+
+Published package name:
+
+```bash
+python -m pip install SCOPE-RTM
+```
+
+Import name:
+
+```python
+import scope
+```
+
+### 1. Clone the repository
+
+```bash
+git clone <your-repo-url> scope
+cd scope
+```
+
+### 2. Fetch the pinned upstream SCOPE assets
+
+```bash
+python scripts/fetch_upstream_scope.py
+```
+
+If you installed the package in an environment already, the same helper is available as:
+
+```bash
+scope-fetch-upstream
+```
+
+### 3. Create an environment and install
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+```
+
+### 4. Verify the install
+
+```bash
+PYTHONPATH=src python examples/basic_scene_reflectance.py
+PYTHONPATH=src python -m pytest -q tests/test_scope_benchmark_parity.py tests/test_scope_timeseries_benchmark_parity.py
+```
+
+## 5-Minute Quickstart
+
+### Minimal scene reflectance run
+
+```bash
+PYTHONPATH=src python examples/basic_scene_reflectance.py
+```
+
+Expected output:
+
+```json
+{
+  "product": "reflectance",
+  "dims": {"y": 1, "x": 1, "time": 1, "wavelength": 2001},
+  "rsot_650nm": 0.047138178221010914,
+  "rsot_865nm": 0.4100649627325952,
+  "rsot_1600nm": 0.26994893328935227
+}
+```
+
+### High-level workflow run
+
+```bash
+PYTHONPATH=src python examples/scope_workflow_demo.py
+```
+
+Expected output:
+
+```json
+{
+  "product": "scope_workflow",
+  "components": [
+    "reflectance",
+    "reflectance_directional",
+    "reflectance_profile",
+    "fluorescence",
+    "fluorescence_directional",
+    "fluorescence_profile"
+  ],
+  "rsot_650nm_t0": 0.04522854188089004,
+  "LoF_peak_t0": 1.985767010834904e-05,
+  "LoF_peak_wavelength_t0": 744.0
+}
+```
+
+## Main Entry Points
+
+For most users, the preferred entry points are:
+
+- [`ScopeGridRunner.run_scope_dataset(...)`](src/scope/runners/grid.py)
+  High-level reflectance/fluorescence/thermal workflow dispatch from prepared `xarray` inputs.
+- [`prepare_scope_input_dataset(...)`](src/scope/io/prepare.py)
+  Build a runner-ready dataset from weather, observation, and Sentinel-2 bio inputs.
+- [`write_netcdf_dataset(...)`](src/scope/io/export.py)
+  Persist prepared or simulated outputs to NetCDF with safe backend selection and compression handling.
+
+For direct lower-level use:
+
+- [`FluspectModel`](src/scope/spectral/fluspect.py)
+- [`CanopyReflectanceModel`](src/scope/canopy/reflectance.py)
+- [`CanopyFluorescenceModel`](src/scope/canopy/fluorescence.py)
+- [`CanopyThermalRadianceModel`](src/scope/canopy/thermal.py)
+- [`CanopyEnergyBalanceModel`](src/scope/energy/balance.py)
+
+## Documentation Map
+
+- [Installation Guide](docs/installation.md)
+- [Quickstart](docs/quickstart.md)
+- [Model Mechanics](docs/model-mechanics.md)
+- [Input / Output Reference](docs/input-output-reference.md)
+- [Examples](docs/examples.md)
+- [Production Notes](docs/production-notes.md)
+- [Benchmark Policy](docs/benchmark-policy.md)
+
+Build the docs locally with:
+
+```bash
+python -m pip install -e ".[docs]"
+mkdocs build --strict
+```
+
+## Production Notes
+
+- Asset-backed constructors such as `from_scope_assets(...)` require an upstream SCOPE checkout. The recommended path is `scope-fetch-upstream`.
+- The default CI suite runs parity tests in live-or-pregenerated mode. On machines without MATLAB, the tests compare against checked-in MATLAB fixtures.
+- The self-hosted GPU and live-MATLAB lanes remain optional operational lanes; see [docs/benchmark-policy.md](docs/benchmark-policy.md).
+- Documentation can be built locally with `mkdocs build --strict` and is deployed by the dedicated GitHub Pages workflow.
+- Distribution artifacts can be built locally with `python -m build` and validated with `python -m twine check dist/*`.
+
+## Testing
+
+Run the default suite with:
+
+```bash
+PYTHONPATH=src python -m pytest -q
+```
+
+The strongest automated checks currently include:
+
+- kernel parity and execution-mode regression tests
+- ROI/time runner consistency tests
+- committed scene and time-series benchmark summary regression tests
+- live-or-pregenerated MATLAB parity tests for the single-scene and time-series benchmark gates
+
+## Release Workflows
+
+- `.github/workflows/release.yml`
+  Builds `sdist` and wheel artifacts for `SCOPE-RTM`, validates them with `twine check`, and auto-publishes to PyPI on version tags. Manual dispatch still supports TestPyPI or PyPI.
+- `.github/workflows/docs.yml`
+  Builds the MkDocs site and deploys it to GitHub Pages.

scope_rtm-0.1.0/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "SCOPE-RTM"
+version = "0.1.0"
+description = "PyTorch reimplementation of the SCOPE radiative transfer model."
+readme = "README.md"
+authors = [{name = "Marc Yin", email = "marc.yin@example.com"}]
+license = "GPL-3.0-only"
+requires-python = ">=3.10"
+keywords = ["scope", "radiative-transfer", "remote-sensing", "pytorch", "fluorescence", "thermal"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Atmospheric Science",
+]
+dependencies = [
+    "torch>=2.2",
+    "numpy>=1.26",
+    "scipy>=1.11",
+    "xarray>=2024.1",
+    "rioxarray>=0.15",
+    "pandas>=2.2"
+]
+
+[project.scripts]
+scope-fetch-upstream = "scope.cli.fetch_upstream:main"
+scope-prepare = "scope.cli.prepare_scope_input:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.1",
+    "pytest-cov>=4.1",
+    "prosail>=2.0",
+    "rich>=13.7"
+]
+docs = [
+    "mkdocs>=1.6",
+    "mkdocs-material>=9.5",
+    "mkdocs-mermaid2-plugin>=1.2"
+]
+release = [
+    "build>=1.2",
+    "twine>=5.1"
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+addopts = "-ra"
+testpaths = ["tests"]
+pythonpath = ["src"]

scope_rtm-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

scope_rtm-0.1.0/src/SCOPE_RTM.egg-info/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: SCOPE-RTM
+Version: 0.1.0
+Summary: PyTorch reimplementation of the SCOPE radiative transfer model.
+Author-email: Marc Yin <marc.yin@example.com>
+License-Expression: GPL-3.0-only
+Keywords: scope,radiative-transfer,remote-sensing,pytorch,fluorescence,thermal
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: torch>=2.2
+Requires-Dist: numpy>=1.26
+Requires-Dist: scipy>=1.11
+Requires-Dist: xarray>=2024.1
+Requires-Dist: rioxarray>=0.15
+Requires-Dist: pandas>=2.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8.1; extra == "dev"
+Requires-Dist: pytest-cov>=4.1; extra == "dev"
+Requires-Dist: prosail>=2.0; extra == "dev"
+Requires-Dist: rich>=13.7; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Requires-Dist: mkdocs-mermaid2-plugin>=1.2; extra == "docs"
+Provides-Extra: release
+Requires-Dist: build>=1.2; extra == "release"
+Requires-Dist: twine>=5.1; extra == "release"
+
+# SCOPE
+
+PyTorch-first implementation of the SCOPE canopy radiative transfer model for reflectance, fluorescence, thermal radiance, and coupled energy-balance workflows.
+
+## What It Is
+
+`scope` is designed for users who need:
+
+- asset-backed SCOPE physics in Python
+- batched ROI/time execution on `xarray` datasets
+- differentiable model components in PyTorch
+- reproducible MATLAB parity checks in CI and local development
+
+The current implementation supports:
+
+- leaf optics through FLUSPECT
+- canopy reflectance through 4SAIL-based transport
+- layered fluorescence and thermal radiative transfer
+- leaf biochemistry and coupled energy balance
+- directional and vertical-profile outputs on the homogeneous canopy path
+- ROI/time workflows with `xarray` input and output assembly
+
+## Install
+
+Published package name:
+
+```bash
+python -m pip install SCOPE-RTM
+```
+
+Import name:
+
+```python
+import scope
+```
+
+### 1. Clone the repository
+
+```bash
+git clone <your-repo-url> scope
+cd scope
+```
+
+### 2. Fetch the pinned upstream SCOPE assets
+
+```bash
+python scripts/fetch_upstream_scope.py
+```
+
+If you installed the package in an environment already, the same helper is available as:
+
+```bash
+scope-fetch-upstream
+```
+
+### 3. Create an environment and install
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+```
+
+### 4. Verify the install
+
+```bash
+PYTHONPATH=src python examples/basic_scene_reflectance.py
+PYTHONPATH=src python -m pytest -q tests/test_scope_benchmark_parity.py tests/test_scope_timeseries_benchmark_parity.py
+```
+
+## 5-Minute Quickstart
+
+### Minimal scene reflectance run
+
+```bash
+PYTHONPATH=src python examples/basic_scene_reflectance.py
+```
+
+Expected output:
+
+```json
+{
+  "product": "reflectance",
+  "dims": {"y": 1, "x": 1, "time": 1, "wavelength": 2001},
+  "rsot_650nm": 0.047138178221010914,
+  "rsot_865nm": 0.4100649627325952,
+  "rsot_1600nm": 0.26994893328935227
+}
+```
+
+### High-level workflow run
+
+```bash
+PYTHONPATH=src python examples/scope_workflow_demo.py
+```
+
+Expected output:
+
+```json
+{
+  "product": "scope_workflow",
+  "components": [
+    "reflectance",
+    "reflectance_directional",
+    "reflectance_profile",
+    "fluorescence",
+    "fluorescence_directional",
+    "fluorescence_profile"
+  ],
+  "rsot_650nm_t0": 0.04522854188089004,
+  "LoF_peak_t0": 1.985767010834904e-05,
+  "LoF_peak_wavelength_t0": 744.0
+}
+```
+
+## Main Entry Points
+
+For most users, the preferred entry points are:
+
+- [`ScopeGridRunner.run_scope_dataset(...)`](src/scope/runners/grid.py)
+  High-level reflectance/fluorescence/thermal workflow dispatch from prepared `xarray` inputs.
+- [`prepare_scope_input_dataset(...)`](src/scope/io/prepare.py)
+  Build a runner-ready dataset from weather, observation, and Sentinel-2 bio inputs.
+- [`write_netcdf_dataset(...)`](src/scope/io/export.py)
+  Persist prepared or simulated outputs to NetCDF with safe backend selection and compression handling.
+
+For direct lower-level use:
+
+- [`FluspectModel`](src/scope/spectral/fluspect.py)
+- [`CanopyReflectanceModel`](src/scope/canopy/reflectance.py)
+- [`CanopyFluorescenceModel`](src/scope/canopy/fluorescence.py)
+- [`CanopyThermalRadianceModel`](src/scope/canopy/thermal.py)
+- [`CanopyEnergyBalanceModel`](src/scope/energy/balance.py)
+
+## Documentation Map
+
+- [Installation Guide](docs/installation.md)
+- [Quickstart](docs/quickstart.md)
+- [Model Mechanics](docs/model-mechanics.md)
+- [Input / Output Reference](docs/input-output-reference.md)
+- [Examples](docs/examples.md)
+- [Production Notes](docs/production-notes.md)
+- [Benchmark Policy](docs/benchmark-policy.md)
+
+Build the docs locally with:
+
+```bash
+python -m pip install -e ".[docs]"
+mkdocs build --strict
+```
+
+## Production Notes
+
+- Asset-backed constructors such as `from_scope_assets(...)` require an upstream SCOPE checkout. The recommended path is `scope-fetch-upstream`.
+- The default CI suite runs parity tests in live-or-pregenerated mode. On machines without MATLAB, the tests compare against checked-in MATLAB fixtures.
+- The self-hosted GPU and live-MATLAB lanes remain optional operational lanes; see [docs/benchmark-policy.md](docs/benchmark-policy.md).
+- Documentation can be built locally with `mkdocs build --strict` and is deployed by the dedicated GitHub Pages workflow.
+- Distribution artifacts can be built locally with `python -m build` and validated with `python -m twine check dist/*`.
+
+## Testing
+
+Run the default suite with:
+
+```bash
+PYTHONPATH=src python -m pytest -q
+```
+
+The strongest automated checks currently include:
+
+- kernel parity and execution-mode regression tests
+- ROI/time runner consistency tests
+- committed scene and time-series benchmark summary regression tests
+- live-or-pregenerated MATLAB parity tests for the single-scene and time-series benchmark gates
+
+## Release Workflows
+
+- `.github/workflows/release.yml`
+  Builds `sdist` and wheel artifacts for `SCOPE-RTM`, validates them with `twine check`, and auto-publishes to PyPI on version tags. Manual dispatch still supports TestPyPI or PyPI.
+- `.github/workflows/docs.yml`
+  Builds the MkDocs site and deploys it to GitHub Pages.