Installation¶
Instructions¶
There are several ways to install PyMOC and its dependencies on your system. As PyMOC is intended primarily as an educational instrument, we highly encourage you to download the source from GitHub and either install the model locally or utilize our pre-build Docker container. Regardless, instructions are provided for installing a packaged version of the PyMOC modules from pip for those who are not interested in what’s going on under the hood. Notice however, that the pip installation will not include the code directory or examples.
The Recommended Way: Building from Source¶
To install PyMOC from source, you will need to ensure that you have Python 2.7 or 3, and the proper versions of numpy and scipy installed on your system, as for the above managed installation instructions.
Rather than installing PyMoc via pip or conda, however, you will instead directly clone the code repository using git into whatever local directory you would like to work with the code in
$ git clone https://github.com/pymoc/pymoc.git
You can then navigate into the pymoc directory, and install the model
$ cd pymoc
$ python setup.py install
If you plan on modifying the model code for your own purposes, you should install in development mode instead
$ python setup.py develop
Should you receive an error from either of the above installation commands
regarding system privileges, you will need to either install as root (via
sudo), or if you do not have root privileges install for only your user
by passing the --user flag to the setup script.
The Easy Way to get the PyMOC Modules: Installing with pip or conda¶
PyMOC is available on the Python Package Index (PyPi), and can be installed via pip in a terminal window. First, make sure you have numpy and scipy installed:
$ pip install numpy>=1.13
$ pip install scipy>=1.3
Once these dependencies are installed, PyMOC can be installed via
$ pip install py-moc
If you do not have Python or pip configured on your system, instructions can be found on Real Python and in the PyPa documentation.
Alternatively, you may want to manage your Python environment using the Anaconda distribution. Once you have installed Anaconda, you can follow analagous steps to those required to install via pip
$ conda install -c anaconda numpy=1.13
$ conda install -c anaconda scipy=1.3
$ conda install -c anaconda py-moc
Getting a Working Environment the Zero Configuration Way: Running in Docker¶
If you are just getting started with Python, and have not (or don’t want to) configure your system to run PyMOC by hand, a containerized Docker environment is available to users. A Docker container is a pre- packaged software execution environment, with all software dependencies installed and ready to go, meaning that end users are not required to go through tedious system configuration to get up and running. For those familiar with Git & GitHub, Docker serves a similar purpose, but for full software environments rather than code. Our automated testing suite runs in the same Docker container provided here, so for beginners containerization is an easy alternative to avoid issues surrounding package version and configuration.
To get started with Docker, sign up for a free account on Docker Hub, and download and install the desktop software for your operating system (available for Windows, MacOS, and Linux). Once you have installed and logged in to desktop software, open your preferred terminal and download the latest version of the PyMOC image:
$ docker pull pymoc/pymoc:latest
Next, navigate to the directory where you want to work on the PyMOC code, and clone the repository from GitHub:
$ git clone https://github.com/pymoc/PyMOC.git
If you don’t have git installed, you can also download a zipfile of the latest source code from https://github.com/pymoc/PyMOC/archive/master.zip.
Once the code has been cloned or downloaded and unzipped, you’ll need to create and start a local container from the PyMOC image:
$ docker create -it --name pymoc -v <Path to Your Code>:/pymoc/ pymoc:latest
$ docker start pymoc
From there, you can start a bash session inside of the container via:
$ docker exec -it pymoc bash
And proceed with the instructions for installing and running the model outlined in The Recommended Way, following the dependency and system configuration steps.