atmolidarpy 0.2.0

Standalone atmospheric lidar data processing package

atmolidarpy

atmolidarpy is the PyPI distribution for the standalone atmospheric lidar processing package imported as lidarpy.

The project was migrated out of the former gfatpy.lidar submodule so that the lidar processing code can be installed, tested, documented and released on its own. It includes RAW Licel conversion, preprocessing, quicklooks, synthetic signal generation, retrieval routines, SCC support modules and package data for known lidar systems.

Current public documentation:

• Documentation site
• Module reference index

Documentation Map

• Overview: package scope and repository map.
• Getting started: install, first import, first validation and expected results.
• Processing workflow: operational data flow from RAW files to NetCDF, preprocessing, quicklooks and retrieval checks.
• Examples: runnable snippets for synthetic signals, preprocessing and SCC client contracts.
• Operational guide: local, CI, release, rollback, troubleshooting and runtime boundaries.
• References: scientific references and public module index.
• Contributing: development workflow and documentation maintenance.

Install

For users:

python -m pip install atmolidarpy
python -c "import lidarpy; print(lidarpy.__version__)"

Expected result: Python imports lidarpy without needing the old gfatpy package. The distribution name and import name are intentionally different: install atmolidarpy, import lidarpy.

For local development:

uv sync --group dev
$env:PYTHONPATH = "src"
$env:MPLBACKEND = "Agg"
.\.venv\Scripts\python -m pytest tests -q -m "not slow"

The full suite includes RAW fixture conversion and can create large temporary NetCDF files. On Windows, run large groups in chunks and keep pytest temporary directories inside the repository.

Repository Shape

• src/lidarpy/nc_convert: RAW/Licel discovery and NetCDF conversion.
• src/lidarpy/preprocessing: correction pipeline, overlap and gluing support.
• src/lidarpy/plot: quicklook plotting.
• src/lidarpy/retrieval: Klett, Raman, overlap, calibration, ABLH detection and synthetic validation helpers.
• src/lidarpy/atmo: molecular atmosphere and Rayleigh utilities.
• src/lidarpy/depolarization: calibration and retrieval helpers.
• src/lidarpy/scc: SCC conversion, client, resources and plotting helpers.
• tests: focused unit, integration, packaging, SCC, docs and synthetic tests.
• docs: static GitHub Pages source.
• scripts: documentation build and figure generation.

Release

Current package version: 0.2.0.

The package is published as atmolidarpy on PyPI through GitHub Actions Trusted Publishing. Releases are tag-driven:

git tag v0.2.0
git push origin v0.2.0

The Publish Package workflow builds sdist and wheel artifacts, checks them with Twine and publishes to PyPI from the GitHub environment named pypi.

Versioning policy while the project remains alpha:

• Bug fixes that keep the public API compatible use patch releases within the current minor series, for example 0.2.1.
• Public API additions or behavior changes use 0.2.0, 0.3.0, etc.
• 1.0.0 is reserved for the first stable API intended for production dependants such as gfat-worker.

What is New in 0.2.0

• Added lidarpy.retrieval.ablh with ABLH detection on common time, range products from lidarpy datasets and Cloudnet ceilometer backscatter products.
• Added WCT and temporal-variance ABLH methods with synthetic 2D tests against known simulated layer height.
• Added a Cloudnet CHM15k Granada workbench that writes ABLH NetCDF products and a quicklook overlaying detected layer heights.

Rollback is normally operational rather than destructive: publish a corrected new version, or pin downstream environments to the last known good version. Do not delete release tags or PyPI files unless there is a severe security or legal reason.