Table of Contents
- Installation
- Conda Packages
- Official Releases
- Conda Packages
Building from Source
Building Meep directly from the source code can be challenging for users unfamiliar with building Unix software. This is mainly because of the numerous prerequisites that must be installed as well as the need to specify in the build scripts where these packages are to be found. Personal bookkeeping software for mac.
That resulted in good libctl/meepswigbugworkaround.i and libctl/meepenumrenames.i when make was run, but to fix libctl/meeprenames.i, I punted and just copied that file over from a meep 1.2.1 distribution. For the instructions that follow, I used this guide as a guide and made modifications to get things to work on OS-X. When you run Meep, you can first set the OMPNUMTHREADS environment variable to the number of threads you want OpenMP to use. Separating Build and Source Paths. Meep supports 'VPATH' builds, where you compile in a separate directory from the source directory. This is helpful if you want to keep the source directory in a pristine state, or if.
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, libGDSII, MPI, OpenMP, HDF5, Python, and 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 master branch of the Meep repository on Github if you have Autotools installed. For more information, see Build From Source.
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. The precompiled binaries run as fast or faster than the typical build from source, are simple to install, can be upgraded easily, and take advantage of newer compilers and dependencies than those available in typical systems (e.g., gcc 7.3.0 vs. Ubuntu 16.04's 5.4; a gap of nearly three years of advances in compiler optimization). Obviously, building from source can still provide advantages if you have access to special hardware or performance libraries that require specific compiler flags (e.g., icc); building from source is also required if you are interested in working on the Meep source code, are performing system-wide installations on a server, or are using systems unsupported by Conda (e.g., supercomputers with Cray MPI).
Binary packages for serial and parallel PyMeep on Linux and macOS are currently available (64 bit architectures only), and are updated with each new Meep release. Note: the Conda packages will not work on native Windows (unless you install the Ubuntu terminal app) and do not include the Scheme interface which must be built from source. 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:
Next, we create a Conda environment for PyMeep to isolate it from other Python libraries that may be installed.
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.
Now, python -c 'import meep'
(or python3 -c 'import meep'
) should work, and you can try running some of the examples in meep/python/examples.
Note: There is currently an issue with openblas 0.3.5 that causes segmentation faults on newer Skylake X-series cpus. If import meep
results in an 'illegal instruction' error, downgrade openblas to version 0.3.4
as follows:
Warning: The pymeep
package is built to work with OpenBLAS, which means numpy should also use OpenBLAS. Since the default numpy is built with MKL, installing other packages into the environment may cause conda to switch to an MKL-based numpy. This can cause segmentation faults when calling MPB. To work around this, you can make sure the no-mkl
conda package is installed, make sure you're getting packages from the conda-forge
channel (they use OpenBLAS for everything), or as a last resort, run import meep
before importing any other library that is linked to MKL. When installing additional packages into the meep
environment, you should always try to install using the -c conda-forge
flag. conda
can occasionally be too eager in updating packages to new versions which can leave the environment unstable. If running conda install -c conda-forge
attempts to replace conda-forge
packages with equivalent versions from the defaults
channel, you can force it to only use channels you specify (i.e., arguments to the -c
flag) with the --override-channels
flag.
Installing parallel PyMeep follows the same pattern, but the package 'build string' must be specified to bring in the MPI variant:
The first *
requests the latest version of Pymeep, and the mpi_mpich_*
says to get a version that includes 'mpi_mpich' in the build string (the packages are currently built with the MPICH implementation of MPI).
The environment includes mpi4py
, so you can run an MPI job with 4 processes like this:
If you run into issues, make sure your PYTHONPATH
environment variable is unset.
Note: If you experience crashes when using matplotlib
on macOS, try importing meep
before importing matplotlib
. In addition add the following line to your ~/.matplotlib/matplotlibrc
file to force the TkAgg
backend:
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:
Note: To update, pymeep
, you can do conda update -c conda-forge pymeep
. If you run into problems (e.g. some other update has interfered with your environment), you can instead create a new environment from scratch each time.
Older Releases
Older releases of PyMeep are available on the conda-forge
channel. The full list of available versions is here. Examples:
Note that parallel (MPI) versions are only available with pymeep >= 1.8.0
.
Nightly Builds
To experiment with new features before they are distributed in an official release, you can try the nightly-development builds. They are hosted on the simpetus
channel. Currently, the nightly builds are only available for Python 2.7 and 3.6.
Version Number
You can determine the version number as well as the most recent commit of the Meep module via:
This will show something like 1.11.0-1-g415bc8eb
where the first three digits (1.11.0
) refer to a stable tarball release, the following digit is the number of commits after this stable release, and the eight characters following the g
in the final string refer to the commit hash.
Non-Networked Systems
To install the PyMeep Conda package on a non-networked system, using the bz2 tarball of the official release or nightly build will not work without the dependencies. A possible workaround is Conda-Pack.
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:
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.
- Install Homebrew: download from the Homebrew site and follow the instructions there.
- 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
Instructions For How To Download Meep Onto Macos Catalina
Now, install the Harminv, libctl, MPB, and Meep packages from source. Download Harminv and, in the harminv
directory, do:
Use the same commands for libctl, MPB, and Meep. For more detailed information, see Build From Source.
You are done, and can now run Meep (Scheme interface) just by typing meep
. You can run make check
in the meep directory if you want to perform a self-test.
To build the latest version of Meep from source on macOS Sierra, follow these instructions.
Installation on Windows
Native Windows installation is currently unsupported. The recommended procedure is to install Ubuntu using the Windows Subsystem for Linux. This gives you access to a bash terminal running Ubuntu from within Windows. From there you can install the Conda packages as described above. The drawback is that you can't see plots from matplotlib (though saving them to disk and opening them from Windows works fine). The easiest way around this is to add the jupyter
package to the conda create ..
command. This will allow you to run a Jupyter notebook in the browser, and from there you can visualize plots interactively.
Nowadays, installing FFTW on MacOS X is much like on any othe Unix system. In ancient times, a lot more work was required, and some of those obsolete instructions are preserved below for historical interest.
Installing FFTW on MacOS X
To install FFTW on MacOS X, all you should have the Apple developertools installed, so that you can open up a terminal window and compileFFTW just as you would on any other Unix system:./configure && make
to compile, ande.g. sudo make install
to switch to root
andinstall in /usr/local
. (Note that sudo
asksfor your password, not root
's; alternatively,you can just use su
, assuming that your root
account is enabled (it isn't by default).)
The multi-threaded version (with POSIX threads) also works fine(./configure --enable-threads
).
Precompiled MacOS X libraries via Fink
Instead of the above, the Fink project has puttogether precompiled/prepackaged versions of FFTW 2.x and FFTW 3.x for MacOS X.
Fink provides a collection of free-software Unix tools packaged forMacOS X, based on the excellent package and system-maintainance toolsdeveloped for Debian GNU/Linux
Instructions For How To Download Meep Onto Macos High Sierra
Precompiled packages for CodeWarrior (ancient compiler)
Greg Allen graciously posted a Macpackage of FFTW 2.1.3 and BenchFFT, for CodeWarrior 5 I believe.
In the past, I had created precompiled packages of FFTW for Metrowerks CodeWarrior, includingPPC and 68k libraries. Since my version of CodeWarrior (Pro 2) wasbecoming more and more out of date, I stopped doing this.The last version I packaged in this way was FFTW 2.0.1: fftw-2.0.1.sit.bin.
If you are interested in creating precompiled CodeWarrior packagesof FFTW 3.x (e.g. for MacOS 9), please let us know (and give us a ride on your Tardis).
Compiling FFTW 2.x on MacOS 9
Compiling FFTW yourself on the MacOS is fairly straightforward.For example, this is the outline of the steps to compile thecomplex-transform library using CodeWarrior.
- Download and unpack the FFTW archive (
.tar.gz
format); StuffitExpander (available gratis) should have no problem with this.(Alternatively, you can download standalone gunzipand untarprograms.) - Create an empty CodeWarrior project for the library, anddrag the
fftw
subfolder of the FFTW package onto theproject (this will add all the.c
and.h
files). - Go into the project preferences, change the project type to alibrary, and turn all the optimizations on. You will also also needto go to 'Access Paths' and move the
fftw
folder into the'System Paths' section (since our code includes it as).
- Compile.
The recommended way to install PyMeep is using the Conda package manager. The precompiled binaries run as fast or faster than the typical build from source, are simple to install, can be upgraded easily, and take advantage of newer compilers and dependencies than those available in typical systems (e.g., gcc 7.3.0 vs. Ubuntu 16.04's 5.4; a gap of nearly three years of advances in compiler optimization). Obviously, building from source can still provide advantages if you have access to special hardware or performance libraries that require specific compiler flags (e.g., icc); building from source is also required if you are interested in working on the Meep source code, are performing system-wide installations on a server, or are using systems unsupported by Conda (e.g., supercomputers with Cray MPI).
Binary packages for serial and parallel PyMeep on Linux and macOS are currently available (64 bit architectures only), and are updated with each new Meep release. Note: the Conda packages will not work on native Windows (unless you install the Ubuntu terminal app) and do not include the Scheme interface which must be built from source. 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:
Next, we create a Conda environment for PyMeep to isolate it from other Python libraries that may be installed.
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.
Now, python -c 'import meep'
(or python3 -c 'import meep'
) should work, and you can try running some of the examples in meep/python/examples.
Note: There is currently an issue with openblas 0.3.5 that causes segmentation faults on newer Skylake X-series cpus. If import meep
results in an 'illegal instruction' error, downgrade openblas to version 0.3.4
as follows:
Warning: The pymeep
package is built to work with OpenBLAS, which means numpy should also use OpenBLAS. Since the default numpy is built with MKL, installing other packages into the environment may cause conda to switch to an MKL-based numpy. This can cause segmentation faults when calling MPB. To work around this, you can make sure the no-mkl
conda package is installed, make sure you're getting packages from the conda-forge
channel (they use OpenBLAS for everything), or as a last resort, run import meep
before importing any other library that is linked to MKL. When installing additional packages into the meep
environment, you should always try to install using the -c conda-forge
flag. conda
can occasionally be too eager in updating packages to new versions which can leave the environment unstable. If running conda install -c conda-forge
attempts to replace conda-forge
packages with equivalent versions from the defaults
channel, you can force it to only use channels you specify (i.e., arguments to the -c
flag) with the --override-channels
flag.
Installing parallel PyMeep follows the same pattern, but the package 'build string' must be specified to bring in the MPI variant:
The first *
requests the latest version of Pymeep, and the mpi_mpich_*
says to get a version that includes 'mpi_mpich' in the build string (the packages are currently built with the MPICH implementation of MPI).
The environment includes mpi4py
, so you can run an MPI job with 4 processes like this:
If you run into issues, make sure your PYTHONPATH
environment variable is unset.
Note: If you experience crashes when using matplotlib
on macOS, try importing meep
before importing matplotlib
. In addition add the following line to your ~/.matplotlib/matplotlibrc
file to force the TkAgg
backend:
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:
Note: To update, pymeep
, you can do conda update -c conda-forge pymeep
. If you run into problems (e.g. some other update has interfered with your environment), you can instead create a new environment from scratch each time.
Older Releases
Older releases of PyMeep are available on the conda-forge
channel. The full list of available versions is here. Examples:
Note that parallel (MPI) versions are only available with pymeep >= 1.8.0
.
Nightly Builds
To experiment with new features before they are distributed in an official release, you can try the nightly-development builds. They are hosted on the simpetus
channel. Currently, the nightly builds are only available for Python 2.7 and 3.6.
Version Number
You can determine the version number as well as the most recent commit of the Meep module via:
This will show something like 1.11.0-1-g415bc8eb
where the first three digits (1.11.0
) refer to a stable tarball release, the following digit is the number of commits after this stable release, and the eight characters following the g
in the final string refer to the commit hash.
Non-Networked Systems
To install the PyMeep Conda package on a non-networked system, using the bz2 tarball of the official release or nightly build will not work without the dependencies. A possible workaround is Conda-Pack.
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:
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.
- Install Homebrew: download from the Homebrew site and follow the instructions there.
- 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
Instructions For How To Download Meep Onto Macos Catalina
Now, install the Harminv, libctl, MPB, and Meep packages from source. Download Harminv and, in the harminv
directory, do:
Use the same commands for libctl, MPB, and Meep. For more detailed information, see Build From Source.
You are done, and can now run Meep (Scheme interface) just by typing meep
. You can run make check
in the meep directory if you want to perform a self-test.
To build the latest version of Meep from source on macOS Sierra, follow these instructions.
Installation on Windows
Native Windows installation is currently unsupported. The recommended procedure is to install Ubuntu using the Windows Subsystem for Linux. This gives you access to a bash terminal running Ubuntu from within Windows. From there you can install the Conda packages as described above. The drawback is that you can't see plots from matplotlib (though saving them to disk and opening them from Windows works fine). The easiest way around this is to add the jupyter
package to the conda create ..
command. This will allow you to run a Jupyter notebook in the browser, and from there you can visualize plots interactively.
Nowadays, installing FFTW on MacOS X is much like on any othe Unix system. In ancient times, a lot more work was required, and some of those obsolete instructions are preserved below for historical interest.
Installing FFTW on MacOS X
To install FFTW on MacOS X, all you should have the Apple developertools installed, so that you can open up a terminal window and compileFFTW just as you would on any other Unix system:./configure && make
to compile, ande.g. sudo make install
to switch to root
andinstall in /usr/local
. (Note that sudo
asksfor your password, not root
's; alternatively,you can just use su
, assuming that your root
account is enabled (it isn't by default).)
The multi-threaded version (with POSIX threads) also works fine(./configure --enable-threads
).
Precompiled MacOS X libraries via Fink
Instead of the above, the Fink project has puttogether precompiled/prepackaged versions of FFTW 2.x and FFTW 3.x for MacOS X.
Fink provides a collection of free-software Unix tools packaged forMacOS X, based on the excellent package and system-maintainance toolsdeveloped for Debian GNU/Linux
Instructions For How To Download Meep Onto Macos High Sierra
Precompiled packages for CodeWarrior (ancient compiler)
Greg Allen graciously posted a Macpackage of FFTW 2.1.3 and BenchFFT, for CodeWarrior 5 I believe.
In the past, I had created precompiled packages of FFTW for Metrowerks CodeWarrior, includingPPC and 68k libraries. Since my version of CodeWarrior (Pro 2) wasbecoming more and more out of date, I stopped doing this.The last version I packaged in this way was FFTW 2.0.1: fftw-2.0.1.sit.bin.
If you are interested in creating precompiled CodeWarrior packagesof FFTW 3.x (e.g. for MacOS 9), please let us know (and give us a ride on your Tardis).
Compiling FFTW 2.x on MacOS 9
Compiling FFTW yourself on the MacOS is fairly straightforward.For example, this is the outline of the steps to compile thecomplex-transform library using CodeWarrior.
- Download and unpack the FFTW archive (
.tar.gz
format); StuffitExpander (available gratis) should have no problem with this.(Alternatively, you can download standalone gunzipand untarprograms.) - Create an empty CodeWarrior project for the library, anddrag the
fftw
subfolder of the FFTW package onto theproject (this will add all the.c
and.h
files). - Go into the project preferences, change the project type to alibrary, and turn all the optimizations on. You will also also needto go to 'Access Paths' and move the
fftw
folder into the'System Paths' section (since our code includes it as).
- Compile.
To compile the corresponding test program (fftw_test
),you'll create a 'console ANSI C' project, adding the library createdabove and the files fftw_test.c
andtest_main.c
(in the tests
subfolder); you'llalso need to modify the access paths as above.
Instructions For How To Download Meep Onto Macos Windows 10
Compiling the rfftw transforms is similar, except that you use therfftw
folder, and rfftw_test.c
for the testprogram.
Instructions For How To Download Meep Onto Macos Mac
CodeWarrior Bugs
CodeWarrior Pro 4 reportedly generates incorrect code whencompiling FFTW 2.x at the highest optimization level (level 4).Supposedly, this problem is fixed in CodeWarrior Pro 5 with all thelatest updates applied. (Thanks to Dan Melomedman for the report, andfor bugging Metrowerks about this.) We haven't heard of problems withother versions of CodeWarrior.
Using FFTW 2.x with the Absoft Compilers
Daniel Barth sent us a couple of notes regarding the compilation ofFFTW 2.x using Absoft's C/C++ and Fortran compilers, version 6.2(circa 2001).
First, the Absoft C compiler seems to have trouble with the Unixline endings (line feeds) in the source files. The source files canbe converted to use Mac line endings (carriage returns) via a programlike NetStripper.
Second, in order to link with Fortran programs using Absoft's ProFortran, add a #define FFTW_FORTRANIZE_UPPERCASE 1
statement to the fftw/config.h
file.