Installation instructions (pip)

These instructions are a work in progress. Suggestions welcome (raise an issue).

For other installation options, see Installation options.

See also:

Please register if you have not already done so. This is very useful in helping us track the extent of usage, and important to the Funding agencies who support this work.

Prerequisites: Before installing, check that you have the Installation Prerequisites.

Quick Installation of all packages

The recommended way to install the latest release of Clawpack, for using PyClaw and/or the Fortran packages, is to give the following pip install command (you might want to first read the notes below to see if you want to change anything in this command):

pip install --src=$HOME/clawpack_src --user -e \
    git+https://github.com/clawpack/clawpack.git@v5.4.0#egg=clawpack-v5.4.0

This will install Clawpack into the directory $HOME/clawpack_src/clawpack-v5.4.0, or the top installation directory can be changed by modifying the –src target.

See Clawpack components for a list of what’s included in this top level.

The –user flag is necessary if you are installing on a shared computer where you do not have root access. If you do have root access and want it to be available to all users, you can omit this flag. See notes below for more information.

In order to use the Fortran codes within Clawpack (classic, amrclaw, or geoclaw), you should then set the environment variable CLAW to point to the clawpack-v5.4.0 directory within the installation directory $HOME/clawpack_src, and FC to point to the desired Fortran compiler, e.g. in the bash shell:

export CLAW=$HOME/clawpack_src/clawpack-v5.4.0
export FC=gfortran

Note: You may want to set CLAW even if you are only using PyClaw, since $CLAW is sometimes used in this documentation to indicate the top level of the Clawpack source directory structure.

See Set environment variables for more information, and Python path if you are having problems with importing Python modules.

Quick Installation of only PyClaw

If you only want to use PyClaw (and associated Python tools, e.g. VisClaw for visualization), they you could do:

pip install clawpack

or, more specifically,

pip install clawpack==5.4.0

However, if you think you might want to use the Fortran packages as well (Classic, AMRClaw, GeoClaw) and/or want easier access to the Python source code, it is recommended that you follow the instructions above for Quick Installation of all packages (or see other Installation options).

Next steps:

Once Clawpack is installed, you can go to one of the following pages to get started:

Notes on using pip to install

This approach clones Git repositories from https://github.com/clawpack/clawpack. If you are comfortable with Git you can use the same top repository to update Clawpack or switch to other versions. However, if you have made any changes to files that are tracked by Git in this set of directories and then try to update or check out other branches, you may run into merge conflicts.

Instead, you can always install another branch by doing a new pip install into a different subdirectory of clawpack_src, e.g.

export CLAW_VERSION=v5.3.1  # used several places in next commands
pip install --src=$HOME/clawpack_src --user -e \
    git+https://github.com/clawpack/clawpack.git@$CLAW_VERSION#egg=clawpack-$CLAW_VERSION
export CLAW=$HOME/clawpack_src/clawpack-$CLAW_VERSION

We also suggest that if you want to experiment extensively with examples or modify an example to solve your own problem, you first copy a directory out of the source code tree to a different location, in order to minimize confusion if you later want to update to a newer version of clawpack. See Creating a new application directory for more details.

If you want to check out the master branch of the clawpack repositories or work with other development versions, see Installation instructions for developers.

Troubleshooting pip install

In case you run into problems with pip install or with changing version, here are some tips:

  • The -e flag (“editable”) results in the the source code remaining in the directory $CLAW, which includes all the Fortran packages as well as Python source.
  • Earlier versions of the installation instructions required setting the environment variable PYTHONPATH. This is not necessary or desirable if you use the pip install option, which instead creates or modifies a file easy-install.pth that is found in the Python site-packages directory (see Python path). The path to the clawpack source is added to this file and hence to the search path for Python. This allows importing Clawpack modules, but note that directories specified here are searched before those specified by the environment variable PYTHONPATH.
  • When the –user flag is omitted, the pip install will modify a system-wide file easy-install.pth to add the path. This requires root permission. When the –user flag is used, this path will instead be added to an easy-install.pth file that is within your user directory structure. See Python path for information on finding these files.
  • If you wish to point to a different version of the Clawpack Python tools, you need to rerun pip install. Or you may need to remove the path from the easy-install.pth file if you want to switch to using PYTHONPATH. See Python path for more information.
  • If you get a Fortran error message when installing, see Setting the Fortran compiler to be used by f2py (pip).

If you cannot get this to work, consider other Installation options and raise an issue to let us know what went wrong.