Installation

There are two ways to install MUSE: one for users who do not wish to modify the source code of MUSE, and another for developers who do.

Note

Windows users and developers may need to install Windows Build Tools. These tools include C/C++ compilers which are needed to build some python dependencies.

MacOS includes compilers by default, hence no action is needed for Mac users.

Linux users may need to install a C compiler, whether GNU gcc or Clang, as well python development packages, depending on their distribution.

  1. Install Visual Studio from the following link: https://visualstudio.microsoft.com/downloads/

  2. Select your preferred edition. Although, the “Community” version is free and contains what is required.

  3. Install Visual Studio by selecting the default options.

  4. Download the Microsoft Visual C++ Build Tools from the following link by downloading Visual Studio 2019: https://visualstudio.microsoft.com/downloads/

  5. Select your preferred edition. The “Community” is free and contains what is required.

  6. Run the installer

  7. Select: Workloads → Desktop development with C++.

  8. Install options: select only the “Windows 10 SDK” (assuming the computer is Windows 10)]. This will come up on the right hand side of the screen.

The installation screen should look similar to the following:

_images/visual-studio-installation.png

For further information, see this link: https://www.scivision.dev/python-windows-visual-c-14-required

For users

MUSE is developed using python, an open-source programming language, which means that there are two steps to the installation process. First, python should be installed. Then so should MUSE.

The simplest method to install python is by downloading the Anaconda distribution. Make sure to choose the appropriate operating system (e.g. windows), python version 3.7, and the 64 bit installer. Once this has been done follow the steps for the anaconda installer, as prompted.

After python is installed we can install MUSE. MUSE can be installed via the Anaconda Prompt (or any terminal on Mac and Linux). This is a command-line interface to python and the python eco-system. In the anaconda prompt, run:

python -m pip install --user git+https://github.com/SGIModel/StarMuse

It should now be possible to run muse. Again, this can be done in the anaconda prompt as follows:

python -m muse --help

Note

Although not strictly necessary, users are encouraged to create an Anaconda virtual environment and install MUSE there, as shown in For developers.

For developers

Although not strictly necessary, creating an Anaconda virtual environment is highly recommended. Anaconda will isolate users and developers from changes occuring on their operating system, and from conflicts between python packages. It also ensures reproducibility from day to day.

Create a virtual env including python with:

conda create -n muse python=3.7

Activate the environment with:

conda activate muse

Later, to recover the system-wide “normal” python, deactivate the environment with:

conda deactivate

The simplest approach is to first download the muse code with git:

git clone https://github.com/SGIModel/StarMuse.git muse

For interested users, there are plenty of good tutorials for git. Next, it is possible to install the working directory into the conda environment:

# On Linux and Mac
cd muse
conda activate muse
python -m pip install -e ".[dev,docs]"

# On Windows
dir muse
conda activate muse
python -m pip install -e ".[dev,docs]"

The quotation marks are needed on some systems or shells, and do not hurt on any. The downloaded code can then be modified. The changes will be automatically reflected in the conda environment.

Tests can be run with the command pytest, from the testing framework of the same name.

The documentation can be built with:

python setup.py docs

The main page for the documentation can then be found at build\sphinx\html\index.html (or build/sphinx/html/index.html on Mac and Linux). The file can viewed from any web browser.

The source files to create the documentation can be found in the docs/ folder from within the main MUSE directory.