Installation
The Merlin library can be installed by using virtual environments and pip or spack.
Contributors to Merlin should follow the Developer Setup below.
Once Merlin has been installed, the installation needs to be configured. See the Configuration page for instructions on how to configure Merlin.
Installing With Virtual Environments & Pip
The most common way to install Merlin is via pip. To accomplish this method of installation we'll need to:
- Set up and activate a virtual environment
- Install Merlin with pip
Creating A Virtual Environment
We'll be creating a Python virtual environment in this section. To do this, run:
Warning
A virtual environment will need to be created for each system type. It's recommended to name the virtual environment venv_<system> to make it easier to switch between them. This documentation will use venv for simplicity to reference the virtual environment.
Tip
Virtual environments provide an isolated environment for working on Python projects to avoid dependency conflicts.
Activating A Virtual Environment
Once the virtual environment is created it can be activated like so:
This will set the Python and Pip path to the virtual environment at venv/bin/python and venv/bin/pip respectively.
The virtual environment name should now display in the terminal, which means it is active. Any calls to pip will install to the virtual environment.
Pip Installing Merlin
Ensure your virtual environment is activated. Once it is, Merlin can be installed using pip:
Verify that Merlin installed properly by ensuring the following command can run:
All set up? See the Configuration page for instructions on how to configure Merlin or check out the Tutorial!
More information on Merlin commands can be found at the Command Line Interface page.
Deactivating A Virtual Environment
Virtualenvs can be exited via the following:
Installing With Spack
The virtualenv method is not the only method to install Merlin in a separate Python install. The Spack method will build Python and all required modules for a specific set of configuration options. These options include the compiler version, system type and Python version. Merlin will then be installed in this specific version allowing for multiple Python versions on a single system without the need for a virtualenv. The py-merlin package builds with python3.6+.
Checkout Spack
Get the latest version of Spack from Github. This is independent from Merlin so make sure Merlin and Spack are in separate directories.
Move into the Spack directory:
The Merlin Spack package is in the develop branch so checkout that branch:
Setup Spack
Source the setup-env.sh or setup-env.csh. This will put Spack in your path and setup module access for later use. This should be done every time the modules are used.
Add compilers if you haven't already:
To see the compilers:
Build Merlin
Merlin can be built with the default compiler which, in general, is the newest gcc compiler, or the compiler can be specified. In the "Specified Compiler Install" example below, we're specifying gcc v7.1.0. Additionally, a different Python version can be specified as part of the package config. The "Python Version Install" example below shows how to build Merlin with Python v3.6.8:
Building Merlin will take a long time, be prepared to wait. It will build Python and all Python modules Merlin needs including numpy.
A tree of all of the packages and their dependencies needed to build the Merlin package can be shown by using the spec keyword.
Activate Merlin
To use Merlin you can activate the module.
Load Python
The associated Python module can then be loaded into your environment, this will only work if you have sourced the setup-env.sh or setup-env.csh.
This will give you a list, the spack version will have a long hash associated with the name.
Example
Now all that's left to do is select which Python to load:
Using the example output above, we could choose to load Python like so:
At this point the module specific Python, Merlin, Maestro and Celery will all be in your path.
Congratulations, you're ready to use Merlin! See the Configuration page for instructions on how to configure Merlin or check out the Tutorial!
More information on Merlin commands can be found at the Command Line Interface page.
Developer Setup
The developer setup can be done via pip or via make. This section will cover how to do both.
Additionally, there is an alternative method to setup Merlin on supercomputers. See the Spack section above for more details.
Make Setup
Visit the Merlin repository on github. Create a fork of the repo and clone it onto your system.
Change directories into the Merlin repo:
Install Merlin with the developer dependencies:
This will create a virtualenv, start it, and install Merlin and it's dependencies for you.
We can make sure it's installed by running:
If you don't see a version number, you may need to restart your virtualenv and try again.
All set up? See the Configuration page for instructions on how to configure Merlin or check out the Tutorial!
More information on Merlin commands can be found at the Command Line Interface page.
Pip Setup
Create a virtual environment and activate it, then install with the additional developer dependencies:
All set up? See the Configuration page for instructions on how to configure Merlin or check out the Tutorial!
More information on Merlin commands can be found at the Command Line Interface page.