Metadata-Version: 2.4
Name: zju-scatt-interface
Version: 0.9.0
Summary: Search, retrieve, integrate, and visualize ZJU-SCATT optical data
Author: Senyi Kong
Maintainer: ZJU-SCATT Team
License-Expression: MIT
Project-URL: Homepage, https://zju_radiation.deep-time.org/
Project-URL: Data browser, https://zju_radiation.deep-time.org/download
Keywords: ZJU-SCATT,atmospheric-radiation,remote-sensing,climate,optical-properties
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: native
Requires-Dist: numpy>=1.23; extra == "native"
Requires-Dist: h5py>=3.9; extra == "native"
Requires-Dist: netCDF4>=1.6; extra == "native"
Provides-Extra: netcdf
Requires-Dist: h5py>=3.9; extra == "netcdf"
Requires-Dist: netCDF4>=1.6; extra == "netcdf"
Provides-Extra: plot
Requires-Dist: matplotlib>=3.7; extra == "plot"
Provides-Extra: all
Requires-Dist: numpy>=1.23; extra == "all"
Requires-Dist: h5py>=3.9; extra == "all"
Requires-Dist: matplotlib>=3.7; extra == "all"
Requires-Dist: netCDF4>=1.6; extra == "all"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: h5py>=3.9; extra == "dev"
Requires-Dist: netCDF4>=1.6; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# 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)

```console
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

```console
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:

```console
zju-scatt doctor
```

## Registration

Direct CLI registration is the default and covers normal use:

```console
zju-scatt register
```

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

```console
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.

```console
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

| Module | Responsibility |
|---|---|
| `auth` | Direct registration, browser-token import, session validation |
| `catalog` | Browse/search, scientific filename metadata, manifests |
| `download` | Resumable downloads and automatic local storage |
| `retrieval` | High-level parameter requests and source selection |
| `planning` | Scheme dependency plans, verified cache, manifests, offline reports |
| `size_distribution` | Array/function/file PSDs, validation, conservative remapping |
| `bulk` | NetCDF loading and PSD-integrated optical properties |
| `schemes` | Typed multi-particle configs and NetCDF4/HDF5 output orchestration |
| `plotting` | Optional scientific plotting |

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:

```console
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:

```console
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](docs/NATIVE_MODEL_FORMATS.md) for the format assessment,
required variables and normalization, supported versions, and reference checks.

```console
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:

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

Run only the CLI tests:

```console
python tests/test_cli.py
```

For a quick source-tree run without installation:

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

In Windows PowerShell, replace the inline assignment with:

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