ZJU-SCATT Interface

zju_scatt_interface is the modular Python and command-line interface for finding, downloading, extracting, integrating, and plotting ZJU-SCATT optical data. It is designed for users in atmospheric radiation, remote sensing, weather, and climate modeling without requiring knowledge of the database's remote directory layout.

The current release candidate is 0.9.0, intended for testing before 1.0.0.

Install from PyPI (after publication)

python -m pip install "zju-scatt-interface[all]==0.9.0"
zju-scatt doctor --offline

Use zju-scatt-interface==0.9.0 for the standard-library-only core. The [all] extra adds scientific file support and plotting. The import name is zju_scatt_interface. Database downloads require separate registration.

This package provides the same zju-scatt command as the earlier zju-scatt distribution; install them in separate virtual environments to avoid command collisions. See docs/PYPI_PUBLICATION.md for release preparation and updates.

Install for development

python -m pip install -e ".[all]"
zju-scatt doctor --offline
zju-scatt --help

The short command remains zju-scatt; the descriptive package and long command are zju_scatt_interface and zju-scatt-interface.

See docs/INSTALLATION.md for Windows, Linux, and macOS setup plus first-run diagnostics.

Run a complete online diagnostic after registration:

zju-scatt doctor

Registration

Direct CLI registration is the default and covers normal use:

zju-scatt register

For users who must complete the website form, the alternative is explicit:

zju-scatt register --method browser

The terminal opens or prints the official page, explains how to obtain the session token, validates it, and stores it without echoing it. --browser-assisted remains a deprecated compatibility alias. Tokens must never be pasted into chat, committed, or included in logs.

Existing workflows retained

All v1 commands are retained during modular migration: browse, list, search, estimate, retrieve, download, bulk, register, session, metadata, and check. Retrieval and explicit downloads create their output directories as needed.

zju-scatt retrieve --particle-type super_spheroid_ice \
  --target-wavelength 0.67um --target-wavelength-mode interp \
  --output-dir zju_scatt_data --yes

The retrieval selector identifies source files in refractive-index (n,k) space and records provenance. The completed calculation pipeline separately records when a single-particle interpolated product was generated, integrates the user PSD, runs physical QA, and can write equivalent NetCDF4 or HDF5 bulk products.

Python modules

See docs/ARCHITECTURE.md, docs/REGISTRATION.md, docs/PARTICLE_PROFILES.md, docs/L1_CEXT_AND_BULK_UNITS.md, docs/REFRACTIVE_INDEX_RESOLUTION.md, docs/SOURCE_DEPENDENCY_PLANNING.md, docs/SIZE_DISTRIBUTIONS.md, docs/BULK_CALCULATION.md, docs/OUTPUT_FORMATS.md, docs/SCHEME_API_AND_CLI.md, docs/MULTIDIMENSIONAL_BULK_SCHEMES.md, docs/CUSTOM_OPTICAL_TABLE_OUTPUT.md, docs/PARTICLE_PARAMETER_REFERENCE.md, docs/PARTICLE_RECIPES.md, docs/GPT_USAGE_GUIDE.md, docs/TROUBLESHOOTING.md, docs/LIVE_TESTING.md, docs/RELEASE_CHECKLIST.md, docs/PROJECT_TASK_LIST.md, docs/STATUS_REPORT_2026-07-23.md, docs/STATUS_UPDATE_2026-07-24.md, docs/STATUS_UPDATE_2026-07-26_PHASE8.md, docs/STATUS_UPDATE_2026-07-26_PHASE9.md, docs/STATUS_UPDATE_2026-07-26_PHASE10.md, docs/STATUS_UPDATE_2026-07-28_PHASE11.md, the configuration in configs/, and the runnable scripts in examples/. Validate a scheme before running any network or scientific calculation:

zju-scatt scheme configs/bulk_scheme.example.json
zju-scatt scheme-sources configs/bulk_scheme.example.json \
  --workspace zju_scatt_data
zju-scatt psd-check configs/bulk_scheme.example.json
zju-scatt bulk-opt validate configs/bulk_scheme.example.json
zju-scatt bulk-opt plan configs/bulk_scheme.example.json --dry-run

Generate the authoritative machine-readable reference or start from a complete particle recipe:

zju-scatt bulk-opt schema --json
zju-scatt bulk-opt schema --particle-type super_spheroid_ice --json
zju-scatt bulk-opt validate configs/recipes/ice_multi_temperature_bulk.json
python examples/example_04_observed_psd_csv.py
python examples/example_05_interpolation_modes.py
python examples/example_16_phase11_release_readiness_validation.py

Verification

Native ARTS 2.x XML, CRTM CloudCoeff release-3 NetCDF/binary, and RTTOV13 HDF5 exports are available through structured JSON templates. See Native model formats for the format assessment, required variables and normalization, supported versions, and reference checks.

python -m pip install -e ".[native]"
python examples/example_17_native_model_formats.py --output native_model_output

First install the package from the project root:

python -m pip install -e .
python -m unittest discover -s tests -v
python -m zju_scatt_interface --help

Run only the CLI tests:

python tests/test_cli.py

For a quick source-tree run without installation:

PYTHONPATH=src python tests/test_cli.py
PYTHONPATH=src python -m unittest discover -s tests -v

In Windows PowerShell, replace the inline assignment with:

$env:PYTHONPATH = (Resolve-Path src).Path
python tests\test_cli.py