ALCF

Installation

Below you can find installation instructions for supported operating systems:

• Linux (recommended)
• Windows with the Windows Subsystem for Linux (Ubuntu)
• macOS

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 system packages.

   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 cython3 pipx
   

   On Fedora, install dependencies with:

    sudo yum install make gcc gfortran hdf5-devel netcdf-devel \
        netcdf-fortran-devel python3-setuptools python3-pip python3-Cython pipx
   

2. Install the ALCF with:

    pipx install alcf
    mkdir -p ~/.local/share/man/man1
    ln -s ~/.local/pipx/venvs/alcf/share/man/man1/alcf*.1 ~/.local/share/man/man1/
   

   Make sure that $HOME/.local/bin is in the PATH environment variable.

Windows

It is recommended to run ALCF on Linux.

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 Ventura on Intel. Installation on Apple ARM (M1 CPUs and later) may be possible but is untested.

1. Install MacPorts.

2. Install required MacPorts packages:

    sudo port install gcc12 hdf5 netcdf netcdf-fortran
    sudo port select --set gcc mp-gcc12
   

3. Install required Python packages:

    python3 -m pip install numpy
   

4. Install the ALCF:

    python3 -m pip install alcf
   

Make sure that /Users/<user>/Library/Python/<version>/bin is included in the PATH environment variable if not already, where <user> is your system user name and <version> is the Python version. This path should be printed by the above command. This can be done by adding this line to the file .zprofile in your home directory and restart the Terminal:

PATH="$PATH:/Users/<user>/Library/Python/<version>/bin"

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.
====

Synopsis
--------

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

Arguments
---------

- `cmd`: See Commands below.
- `options`: Command options.

Commands
--------

- `auto`: Peform automatic processing of model or lidar data.
- `calibrate`: Calibrate lidar backscatter.
- `convert`: Convert input instrument or model data to the ALCF standard NetCDF.
- `lidar`: Process lidar data.
- `model`: Extract model data at a point or along a track.
- `plot`: Plot lidar data.
- `simulate`: Simulate lidar measurements from model data using COSP.
- `stats`: Calculate cloud occurrence statistics.

Options
-------

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

How to uninstall ALCF

To uninstall ALCF on Linux:

pipx uninstall alcf
rm ~/.local/share/man/man1/alcf*.1

To uninstall ALCF on macOS with Anaconda:

pip uninstall alcf

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
pipx install . # Replace pipx with pip for installation in Anaconda.
mkdir -p ~/.local/share/man/man1
ln -s ~/.local/pipx/venvs/alcf/share/man/man1/alcf*.1 ~/.local/share/man/man1/

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.

Preparing a source distribution

To prepare a source distribution:

./download_cosp
python3 setup.py sdist

You might have to replace python3 with python depending on the Python distribution.

The resulting package can be found in dist/alcf-<version>.tar.gz. This is the type of package available on PyPI.

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.5.2 (2023-09-09)

1.5.1 (2023-08-19)

1.5.0 (2023-04-22)

1.4.1 (2023-04-21)

1.4.0 (2023-04-21)

1.3.1 (2023-03-16)

1.3.0 (2023-03-15)

1.2.1 (2023-01-30)

1.2.0 (2022-11-22)

1.1.4 (2021-12-12)

1.1.2 (2021-11-30)

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

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

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

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

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