Pydisort

https://github.com/zoeyzyhu/pydisort
Admin
Pydisort is a Python package and C++ wrapper for the DISORT algorithm that provides...
Tokens:44,763
Snippets:288
Trust Score:6.7
License:GPL-3.0
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install pydisort and run example_01_beam_attenuation.py

Source: https://github.com/zoeyzyhu/pydisort/blob/main/docs/source/examples.rst

Commands to install pydisort and run the first example script from a repository checkout. Requires numpy, torch, and pydisort.

```bash
pip install pydisort
python examples/example_01_beam_attenuation.py
```

--------------------------------

### Install development tools

Source: https://github.com/zoeyzyhu/pydisort/blob/main/docs/source/contribute.rst

Install pytest and pre-commit, then install the pre-commit hooks.

```bash
python -m pip install pytest pre-commit
pre-commit install
```

--------------------------------

### Run all examples as tests with pytest

Source: https://github.com/zoeyzyhu/pydisort/blob/main/examples/README.md

Exercise all four examples via the test suite. See docs/source/testing.rst for full details.

```bash
pytest tests/test_examples.py -v
```

--------------------------------

### Install build dependencies for C++ wrapper

Source: https://github.com/zoeyzyhu/pydisort/blob/main/README.md

Installs required Python packages and runs CMake to configure and build the C++ wrapper. Requires CMake 3.20+, C++17 compiler, and PyTorch installed in the active environment.

```bash
python -m pip install 'torch==2.10.0' numpy pytest 'cmake>=3.20' ninja setuptools 'setuptools-scm>=8' wheel
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=ON
cmake --build build --parallel
```

--------------------------------

### Clone pydisort repository and run Beer-Lambert example

Source: https://github.com/zoeyzyhu/pydisort/blob/main/docs/source/installation.rst

Use these bash commands to clone the pydisort repository, change into its directory, and run the example script. The example ends with 'OK: direct beam reproduces the Beer-Lambert law to machine precision.'

```bash
git clone https://github.com/zoeyzyhu/pydisort.git
cd pydisort
python examples/example_01_beam_attenuation.py
```

--------------------------------

### Install and run Python tests with pytest

Source: https://github.com/zoeyzyhu/pydisort/blob/main/README.md

Installs pydisort and pytest, then runs the Python test suite with verbose output. Requires an installed pydisort package.

```bash
pip install pydisort pytest
pytest tests/ -v
```

--------------------------------

### Install torch with CPU index on Linux

Source: https://github.com/zoeyzyhu/pydisort/blob/main/docs/source/devops.rst

Installs torch 2.10.0, using the CPU index on Linux to avoid downloading a large CUDA wheel, and the default index on other platforms.

```bash
if [[ "$RUNNER_OS" == "Linux" ]]; then
  pip install 'torch==2.10.0' --index-url https://download.pytorch.org/whl/cpu
else
  pip install 'torch==2.10.0'
fi
```

--------------------------------

### Run Example 4 with a Figure

Source: https://github.com/zoeyzyhu/pydisort/blob/main/docs/source/examples.rst

Command to execute the example script and save a plot to two_stream.png. The script runs the validation study and produces a figure.

```bash
python examples/example_04_two_stream_validation.py --plot two_stream.png
```

--------------------------------

### Install PythonicDISORT and threadpoolctl

Source: https://github.com/zoeyzyhu/pydisort/blob/main/docs/source/benchmarks.rst

Installs the PythonicDISORT package and threadpoolctl, which is required for the benchmark.

```bash
pip install PythonicDISORT threadpoolctl
```

--------------------------------

### Install and run PythonicDISORT comparison benchmark

Source: https://github.com/zoeyzyhu/pydisort/blob/main/benchmarks/README.md

Install pydisort, PythonicDISORT, and threadpoolctl, then run the comparison script with various options. The --verify-only flag checks agreement and exits; without it, a default sweep runs. Use --nwave, --threads, and --compare-modes to customize the sweep.

```bash
pip install pydisort PythonicDISORT threadpoolctl
python benchmarks/compare_pythonicdisort.py --verify-only   # seconds
python benchmarks/compare_pythonicdisort.py                 # default sweep
python benchmarks/compare_pythonicdisort.py \
    --nwave 1,10,100,1000 --threads 10 --compare-modes
```

--------------------------------

### Record Python and package versions for development

Source: https://github.com/zoeyzyhu/pydisort/blob/main/docs/source/venv.rst

Prints the Python version and the list of installed packages. Use this when reporting a problem or reproducing a calculation.

```bash
python --version
python -m pip freeze
```

--------------------------------

### Build C++ library and run tests with cmake and ctest

Source: https://github.com/zoeyzyhu/pydisort/blob/main/docs/source/installation.rst

Use these commands to build the C++ library and run its tests. Requires cmake (>= 3.20), a C++17 compiler, and Python 3.10 or newer. The commands install pytest, configure the build with tests enabled, build, install the Python package without build isolation, and run the test suite.

```bash
python -m pip install pytest
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=ON
cmake --build build --parallel
python -m pip install --no-build-isolation .
ctest --test-dir build --output-on-failure
```

--------------------------------

### Create and configure a disort_state object

Source: https://github.com/zoeyzyhu/pydisort/blob/main/docs/source/api.rst

Shows how to instantiate a disort_state object and set its nlyr, nstr, and nphase attributes. The example prints the assigned values to confirm the configuration.

```pycon
>>> import pydisort
>>> ds = pydisort.disort_state()
>>> ds.nlyr, ds.nstr, ds.nphase = 10, 4, 4
>>> ds.nlyr, ds.nstr, ds.nphase
(10, 4, 4)
```

--------------------------------

### Build documentation and run doctests

Source: https://github.com/zoeyzyhu/pydisort/blob/main/docs/source/contribute.rst

Install documentation dependencies, run the documentation extension tests, build HTML docs, and run doctests. The HTML build needs only documentation dependencies; doctests also need the built/installed solver.

```bash
python -m pip install -r docs/requirements.txt
python -m unittest discover -s docs/_ext -p 'test_*.py'
python -m sphinx -E -b html -W --keep-going docs/source docs/_build/html
python -m sphinx -b doctest -W docs/source docs/_build/doctest
```

--------------------------------

### Install pydisort with pip

Source: https://github.com/zoeyzyhu/pydisort/blob/main/docs/source/installation.rst

Installs the latest pydisort release from PyPI. pip automatically installs a compatible torch version.

```bash
python -m pip install pydisort
```

--------------------------------

### Build and run full CTest suite

Source: https://github.com/zoeyzyhu/pydisort/blob/main/docs/source/testing.rst

For development, build from source and run the full CTest suite. Requires following the source-build procedure first. Optionally include examples as tests with -DBUILD_EXAMPLES=ON.

```bash
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=ON
cmake --build build
python -m pip install --no-build-isolation .
ctest --test-dir build --output-on-failure
```

--------------------------------

### Create and configure DisortOptions

Source: https://github.com/zoeyzyhu/pydisort/blob/main/docs/source/api.rst

Shows how to create a DisortOptions instance, set flags and dimensions, and verify the values. The output (10, 10, 10) confirms the settings.

```pycon
>>> import pydisort
>>> op = pydisort.DisortOptions().flags('onlyfl').nwave(10).ncol(10)
>>> op.ds().nlyr, op.ds().nstr, op.ds().nmom = 10, 4, 4
>>> op.nwave(), op.ncol(), op.ds().nlyr
(10, 10, 10)
```

--------------------------------

### DisortOptions.__init__()

Source: https://github.com/zoeyzyhu/pydisort/blob/main/docs/source/api.rst

Initializes a new DisortOptions instance.

```APIDOC
## DisortOptions.__init__()

### Description
Initializes a new DisortOptions instance.

### Method
Constructor

### Signature
`__init__() -> None`

### Parameters
None

### Returns
None
```

--------------------------------

### Verify PythonicDISORT installation

Source: https://github.com/zoeyzyhu/pydisort/blob/main/docs/source/benchmarks.rst

Runs a verification script to ensure PythonicDISORT is correctly installed and functioning.

```bash
python benchmarks/compare_pythonicdisort.py --verify-only
```

--------------------------------

### Install and run mypy for type checking

Source: https://github.com/zoeyzyhu/pydisort/blob/main/docs/source/type_hints.rst

Use these commands to install mypy and check a Python script for type errors. The stub files follow PEP 561, so type checkers automatically find them when the package is installed.

```bash
pip install mypy
mypy your_script.py
```

--------------------------------

### Build commands for two-step build

Source: https://github.com/zoeyzyhu/pydisort/blob/main/docs/source/devops.rst

Run these commands in order to build the project. The first two configure and build the C++ library with CMake, and the third installs the Python extension without build isolation. This order is required because setup.py links against the existing build/lib directory.

```bash
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel
pip install . --no-build-isolation
```

--------------------------------

### Configure DISORT dimensions and options

Source: https://github.com/zoeyzyhu/pydisort/blob/main/README.md

Step 2: create a DisortOptions instance, set radiation flags, and configure the number of layers, streams, moments, and phase-function grid points.

```python
op = DisortOptions().flags("onlyfl,lamber")
op.ds().nlyr = 4
op.ds().nstr = 4
op.ds().nmom = 4
op.ds().nphase = 4
```

--------------------------------

### Register Python examples as CTest tests

Source: https://github.com/zoeyzyhu/pydisort/blob/main/examples/CMakeLists.txt

Registers Python example scripts (matching example_*.py) as CTest tests. Each script is copied to the build directory and executed with the Python3 interpreter; a non-zero exit status indicates the example no longer reproduces its own results, as each script ends with assertions against an analytic solution or conservation law.

```cmake
file(GLOB example_scripts example_*.py)

foreach(script ${example_scripts})
  get_filename_component(name ${script} NAME)
  configure_file(${script} ${CMAKE_CURRENT_BINARY_DIR}/${name} COPYONLY)
  add_test(NAME examples.${name} COMMAND ${Python3_EXECUTABLE} ${name}
           WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR})
endforeach()
```

--------------------------------

### Create test executables for cdisort and cdisort_09

Source: https://github.com/zoeyzyhu/pydisort/blob/main/tests/cdisort213/CMakeLists.txt

Invokes the cdisort_setup_test macro to create two test executables: test_cdisort and test_cdisort_09, the latter for large scale testing.

```cmake
cdisort_setup_test(test_cdisort test_cdisort.c)
cdisort_setup_test(test_cdisort_09 test_cdisort_09.c)
```

--------------------------------

### Create and activate a venv for pydisort

Source: https://github.com/zoeyzyhu/pydisort/blob/main/docs/source/venv.rst

Creates a virtual environment, activates it, upgrades pip, installs pydisort, and verifies the installation. Use this in a bash/zsh shell on macOS or Linux.

```bash
python3 -m venv env
source env/bin/activate
python -m pip install --upgrade pip
python -m pip install pydisort
python -c "import sys, pydisort; print(sys.executable); print(pydisort.__version__)"
```

--------------------------------

### Verify pydisort installation with Python import and version check

Source: https://github.com/zoeyzyhu/pydisort/blob/main/docs/source/installation.rst

Run these Python commands in an interactive session to confirm pydisort is installed and check its version. The expected output is '1.8.5'.

```python
>>> import pydisort
>>> pydisort.__version__
'1.8.5'
```

--------------------------------

### Benchmark results table

Source: https://github.com/zoeyzyhu/pydisort/blob/main/benchmarks/README.md

Example output showing speed-up over PythonicDISORT for various nwave values, comparing single-core and 10-core performance. The single-thread speed-up is about 40x, and multi-threaded speed-up reaches about 335x by 1000 wavenumbers.

```text
Speed-up over PythonicDISORT
   nwave      vs 1 core    vs 10 cores
       1          42.0x          42.4x
      10          41.7x         265.2x
     100          40.8x         314.8x
    1000          39.4x         332.1x
   10000          39.9x         334.7x
```

--------------------------------

### Create a working branch

Source: https://github.com/zoeyzyhu/pydisort/blob/main/docs/source/contribute.rst

Fork the repository if needed, clone your fork, and create a branch for the change.

```bash
git switch -c your-name/describe-the-change
```

--------------------------------

### Install pydisort with pip

Source: https://github.com/zoeyzyhu/pydisort/blob/main/docs/source/index.rst

Install the pydisort package using pip. Prebuilt wheels are available for CPython 3.10-3.14 on selected Linux and macOS targets; no compiler is needed when a matching wheel is available.

```bash
pip install pydisort
```

--------------------------------

### Run cdisort comparison benchmark

Source: https://github.com/zoeyzyhu/pydisort/blob/main/docs/source/benchmarks.rst

Use these commands to run the benchmark script comparing pydisort against cdisort. The --verify-only flag runs only verification, the default runs a sweep, and the third command specifies custom nwave values, threads, and repeat count. No prepared build is needed; the script compiles its own baseline from bench_cdisort.cpp.

```bash
python benchmarks/compare_cdisort.py --verify-only   # seconds
python benchmarks/compare_cdisort.py                 # default sweep
python benchmarks/compare_cdisort.py --nwave 1,10,100,1000,10000 \
    --threads 10 --repeat 3
```

--------------------------------

### Configure DisortOptions and run Disort forward pass

Source: https://github.com/zoeyzyhu/pydisort/blob/main/docs/source/api.rst

Sets up a DisortOptions instance with the flags "onlyfl,lamber", configures layer/stream/moment/phase counts, builds a Disort solver, and runs a forward pass with a single optical-depth column and a beam flux of 3.14159. Ends by gathering flux outputs with gather_flx().

```pycon
>>> import torch
>>> from pydisort import DisortOptions, Disort
>>> op = DisortOptions().flags("onlyfl,lamber")
>>> op.ds().nlyr = 4
>>> op.ds().nstr = 4
>>> op.ds().nmom = 4
>>> op.ds().nphase = 4
>>> ds = Disort(op)
>>> tau = torch.tensor([0.1, 0.2, 0.3, 0.4]).unsqueeze(-1)
>>> flx = ds.forward(tau, fbeam=torch.tensor([3.14159]))
>>> ds.gather_flx()
```

--------------------------------

### Warn if pytest is missing

Source: https://github.com/zoeyzyhu/pydisort/blob/main/tests/CMakeLists.txt

Emits a CMake warning if pytest is not importable, noting that Python tests are registered but will fail until pytest is installed.

```cmake
if(PYTEST_NOT_FOUND)
  message(WARNING
    "pytest is not importable by ${Python3_EXECUTABLE}. The Python tests are "
    "registered but will fail until it is installed (pip install pytest).")
endif()
```
Tokens:
Raw