# Installation

## Building from Source

Building Meep directly from the source code can be challenging for users unfamiliar with building Unix software, mainly because of the many prerequisites that must be installed combined with the need to tell Meep's build scripts where to find these prerequisites.

Meep's build systems uses the standard GNU Autotools ./configure && make && make install machinery, but requires a number of prerequisites in order to obtain a full-featured Meep installation: MPB, Libctl, Harminv, MPI, HDF5, Python, GNU Guile. MPB and Harminv, in turn, require LAPACK and BLAS and FFTW to be installed.

Gzipped tarballs of stable versions of the source are available on the releases page, and you can also do a git clone of the bleeding-edge Meep on Github if you have the GNU Autotools installed. See Build From Source for more information.

The latest version of Meep preinstalled on Ubuntu can be accessed on Amazon Web Services (AWS) Elastic Compute Cloud (EC2) as a free Amazon Machine Image (AMI). To access this AMI, follow these instructions.

## Conda Packages

### Official Releases

The recommended way to install PyMeep is using the Conda package manager. Binary packages for serial and parallel PyMeep on Linux and macOS are currently available (64 bit architectures only), and are updated with each MEEP release. The easiest way to get started is to install Miniconda, which comes with everything necessary to create Python environments with Conda. For example, to install Miniconda with Python 3 on Linux:

wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O miniconda.sh
bash miniconda.sh -b -p <desired_prefix>
export PATH=<desired_prefix>/bin:\$PATH


Next, we create a Conda environment for PyMeep to isolate it from other Python libraries that may be installed.

conda create -n mp -c chogan -c conda-forge pymeep


This creates an environment called "mp" (you can name this anything you like) with PyMeep and all its dependencies. This will default to the version of Python in your Miniconda installation (Python 3 for us since we installed Miniconda3), but if you want to work with Python 2, just add python=2 to the end of the command.

Next, we need to activate the environment before we can start using it.

source activate mp


Now, python -c 'import meep' should work, and you can try running some of the examples in the meep/python/examples directory.

Installing parallel PyMeep follows the same pattern, but the package is called pymeep-parallel.

conda create -n pmp -c chogan -c conda-forge pymeep-parallel
source activate pmp


The environment includes mpi4py, so you can run an MPI job with 4 processes like this:

mpirun -np 4 python <script_name>.py


If you run into issues, make sure your PYTHONPATH environment variable is unset.

Note: For pymeep-parallel on macOS, a bug in openmpi requires that the environment variable TMPDIR be set to a short path like /tmp. Without this workaround, you may see errors similar to this:

[laptop:68818] [[53415,0],0] ORTE_ERROR_LOG: Bad
parameter in file ../../orte/orted/pmix/pmix_server.c at line 264

parameter in file ../../../../../orte/mca/ess/hnp/ess_hnp_module.c at line
666


### Nightly Builds

To experiment with new features before they are distributed in an official release, you can try the nightly development builds. Just put the dev label before the other channels like this:

# Serial pymeep
conda create -n mp_test -c chogan/label/dev -c chogan -c conda-forge pymeep
# Parallel pymeep
conda create -n pmp_test -c chogan/label/dev -c chogan -c conda-forge pymeep-parallel


## Installation on Linux

For most Linux distributions, there should be precompiled packages for most of Meep's prerequisites below, and we highly recommend installing those prerequisites using the available packages for your system whenever possible. Using precompiled packages means that you don't have to worry about how to install things manually. You are using packages which have already been tweaked to work well with your system, and usually your packages will be automatically upgraded when you upgrade the rest of your system. For easy access to the Python interface, we provide a binary installation in the form of Conda packages. Details can be found below.

The following precompiled packages are available: BLAS and LAPACK possibly as part of a package for Atlas BLAS, Guile, MPI, and HDF5. One thing to be careful of is that many distributions split packages into two parts: one main package for the libraries and programs, and a devel package for header files and other things needed to compile software using those libraries. You will need to install both. So, for example, you will probably need both a guile package (probably installed by default) and a guile-dev or guile-devel package (probably not installed by default), and similarly for HDF5 etcetera. You will probably also want to install a libpng-dev or libpng-devel package in order to compile the h5topng utility in h5utils.

The easiest installation is on Ubuntu which has precompiled packages for Meep:

apt-get install meep h5utils


## Installation on macOS

Since macOS is, at its heart, a Unix system, one can, in principle compile and install Meep and all its prerequisites just as on any other Unix system. However, this process is much easier using the Homebrew package to install most of the prerequisites, since it will handle dependencies and other details for you. You will need administrator privileges on your Mac.

The first steps are:

• Install Xcode, the development/compiler package from Apple, free from the Apple Xcode web page.
• Run the following commands in the terminal to compile and install the prerequisites. This may take a while to complete because it will install lots of other stuff first
brew doctor
brew install homebrew/science/hdf5 homebrew/science/openblas guile fftw h5utils


Now, install the Harminv, libctl, MPB, and Meep packages from source. Download Harminv and, in the harminv directory, do:

./configure && make && make install


Use the same commands for libctl, then MPB, then Meep. See Build From Source for more detailed information.

You are done, and can now run Meep just by typing meep. You can run make check in the meep directory if you want to perform a self-test.