ALCF

Automatic Lidar and Ceilometer
Framework

Installation

Below you can find installation instructions for supported operating systems:

You can also build the ALCF from the source code if you want to modify any of its parts.

Linux

The instructions below assume that you enter the commands in the terminal.

  1. Install required programs and libraries:

    On Debian-based Linux distributions (Ubuntu, Debian, Devuan, …), install dependencies with:

     sudo apt install gcc make gfortran libhdf5-dev libnetcdf-dev \
         libnetcdff-dev python3 python3-setuptools python3-pip
    

    On Fedora, install dependencies with:

     sudo yum install make gcc gfortran hdf5-devel netcdf-devel \
         netcdf-fortran-devel python3-setuptools python3-pip
    
  2. Install the ALCF with:

     # To install globally:
     sudo pip3 install alcf --upgrade
    
     # To install in the user's home directory
     # (make sure "$HOME/.local/bin" is in the PATH environment variable):
     pip3 install alcf --upgrade --user
    

Windows

Installation on Windows is possible under the “Windows Subsystem for Linux”.

  1. Install “Ubuntu” from the Microsoft Store. You might have to enable “Windows Subsystem for Linux” under “Windows Features” first.

  2. Open “Ubuntu” from the Start Menu. Update packages with:

     apt update
     apt upgrade
    

    Follow the instructions above for installation on Linux (Debian-based distributions).

    Note: You can use cd /mnt/c/Users/<user>, where <user> is your Windows user name to change the current directory to your home directory, and ls to list the directory contents.

macOS

The installation has been tested on macOS Monterey Intel. Installation on Apple M1 may be possible but is untested.

  1. Install Anaconda.

  2. Install MacPorts.

  3. Install required MacPorts packages:

     sudo port install gcc11 hdf5 netcdf netcdf-fortran
     sudo port select --set gcc mp-gcc11
    
  4. Install the ALCF with:

     pip install alcf
    

On macOS, the default shell zsh does not work with the command-line syntax of the ALCF. It is highly recommeded to run any alcf commands in the bash shell:

% bash
bash-3.2$ alcf
...

Post-installation

After completing the installation, you should be able to run the ALCF in the terminal:

alcf

should output:


alcf - Tool for processing of automatic lidar and ceilometer (ALC) data
and intercomparison with atmospheric models.

Usage:

    alcf <cmd> [<options>]
    alcf <cmd> --help

Arguments:

- `cmd`: see Commands below
- `options`: command options

Options:

`--help`: print help for command
`--debug`: Enable debugging information.

Commands:

- `convert`: convert input instrument or model data to ALCF standard NetCDF
- `model`: extract model data at a point or along a track
- `cosp`: simulate lidar measurements from model data using COSP
- `lidar`: process lidar data
- `stats`: calculate cloud occurrence statistics
- `plot`: plot lidar data
- `plot_stats`: plot lidar statistics
	

Building from the source code

If you want to build the ALCF from the source code, run the following commands in the source code directory:

./download_cosp
pip3 install .
# Replace "pip3" with "pip" if you are using Anaconda.

This will download and unpack ALCF-COSP (a version of COSP with support for ground-based lidars), and compile and install the ALCF. Use this option if you want to customise any parts of the ALCF.

You can also use the following command to continusly change code and have changes applied in the alcf command without re-installing:

python3 setup.py develop
# Replace "python3" with "python" if you are using Anaconda.

Releases

Below is a list of releases of the ALCF. The version numbers follow the Semantic Versioning. Installation instructions have been changing with versions. Please follow the installation instructions in the documentation of the particular version.

1.1.2 (2021-11-30)

Release notes
  • Simplified installation by removing a dependency on CMOR.

1.1.0 (2021-06-29) [documentation] [DOI: 10.5281/zenodo.5153867]

Release notes
  • Support for Vaisala CL61 and NetCDF files produced by BL-VIEW.
  • Improved documentation.

1.0.1 (2021-02-24) [documentation] [DOI: 10.5281/zenodo.5036683]

Release notes
  • Fixed download links to dependencies (udunits archive was removed upstream).

1.0.0 (2021-01-02) [documentation] [DOI: 10.5281/zenodo.4411633]

Release notes
  • First stable release. No change from 1.0.0-beta.3.

1.0.0-beta.3 (2020-10-15) [documentation] [DOI: 10.5281/zenodo.4088217]

Release notes
  • alcf lidar option for coupling of observed data with simulated molecular backscatter.
  • Removal of molecular backscatter in plots (if available).
  • alcf stats filter option now supports "night" and "day" and passing of multiple arguments.
  • New lidar type "default" for re-processing of already processed lidar data.
  • Support for plotting of model cloud liquid water, ice content and cloud fraction.
  • Calculation of lidar ratio changed to effective lidar ratio.
  • Backscatter plots now show effective lidar ratio and cloud mask by default.
  • Changed default vlim for backscatter plots to { 0.1 200 } and default sigma to 5.
  • Output files names are now without colons, which are not compatible with Windows.
  • More accurate plot labels.
  • Improved time sampling: exact profile time bounds are used from weighting.
  • Improved handling of errors and stopping with Ctrl+C.
  • Improved NetCDF metadata.
  • Improved compatibility with newer versions of matplotlib.
  • Fixed clearing of figures in alcf plot backscatter.

1.0.0-beta.2 (2020-05-01) [documentation] [DOI: 10.5281/zenodo.3779518]

Release notes
  • Initial beta release.