Usage

Installation

Note

To use AshDisperse, it is recommended to use a virtual environment (here called ash).

Note

If using conda, it is recommended to first install the numpy, numba and tbb dependencies from conda-forge to ensure system-compatible packages are installed prior to installing AshDisperse.

AshDisperse can be installed from PyPI using pip:

(ash) $ pip install ashdisperse

This will install the package along with dependencies.

Jupyter notebook example

Installing AshDisperse will also download an example of use in a Jupyter notebook and create a command-line function ashdisperse_nb to launch the notebook.

Command-line invocation

Once installed, you can run AshDisperse from the shell command-line using the command:

(ash) $ python -m ashdisperse

Note

AshDisperse uses the Numba package to accelerate computations. Numba compiles the Python code into fast machine code. The initial compilation step can take several seconds to complete, but results in substantial reduction in run times.

Following compilation, the AshDisperse command-line interface will appear, which allows the model to be set up by specifying parameters and meteorological data.

Interactive python session

AshDisperse can be used in an interactive Python session (e.g. in iPython) by importing the package.

First, launch an interactive Python session, e.g.

(ash) $ ipython

and then import AshDisperse (and some other packages that will be useful too):

with the last line indicating that the Numba compilation is complete. Here we have import matplotlib for plotting, numpy for numerical data, and datetime simply for reporting compilation.

The compiled AshDisperse package is now available with the alias ad.

The command-line interface for setting the parameters and meteorological conditions can be accessed using the setup function, returning params and Met objects:

Further details of the parameters and meteorology are available.

Once the parameters and meteorology is set, the solver can be started using the solve function which returns a results object:

Here we have included the optional timer keyword argument that indicates timing of elements of the calculation will be printed.

Further details of the results are available.