diff --git a/.gitignore b/.gitignore index 42cd7be01..edae6fd3c 100644 --- a/.gitignore +++ b/.gitignore @@ -167,3 +167,5 @@ shell.nix model/ *.html + +.idea/ \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index 375fd17e5..26d97f138 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,7 @@ ## Features +- Update documentation for installing MUSE ([#138](https://github.com/SGIModel/MUSE_OS/pull/138)) - Updating pyproject.toml with valid python versions ([#121](https://github.com/SGIModel/MUSE_OS/pull/121)) - Expand CI workflow ([#119](https://github.com/SGIModel/MUSE_OS/pull/119)) - Convert setup.cfg to pyproject.toml and add entrypoint ([#118](https://github.com/SGIModel/MUSE_OS/pull/118)) diff --git a/README.md b/README.md index e3506e63e..3a43fb6e4 100644 --- a/README.md +++ b/README.md @@ -6,92 +6,12 @@ # ModUlar energy system Simulation Environment: MUSE -## Installation +## Installation instructions -### Recommended way +MUSE is available in `PyPI` and therefore it can be installed easily with `pip`. Detailed instructions on how to do that ensuring the right version of Python is used can be found in the Documentation. -The recommended way for **end users** to access and use the tool is via `pipx`. -This will create an isolated environment and install MUSE-OS within in one go, -also letting you to invoke `muse` anywhere in your system. - -1. Install and configure [`pipx`](https://pypa.github.io/pipx/) following the - instructions appropriate for your operative system. Make sure it works well before - moving on. -2. Install MUSE-OS with `pipx install MUSE-OS`. It might take a - while to complete, but afterwards updates should be pretty fast. - - **Note**: `pipx` will use by default a python version which might not be compatible - with MUSE-OS. To select a specific python version use the `--python` flag or set the - environment variable `PIPX_DEFAULT_PYTHON` to the appropriate executable. - See [`pipx install`](https://pypa.github.io/pipx/docs/) documentation for more information. -3. To run MUSE-OS just open a terminal and execute `muse`, with the appropriate input - arguments, if relevant. See section below about usage. - -Whenever there is a new version of MUSE-OS, just run `pipx upgrade MUSE-OS` and -it will be downloaded and installed with no fuss. - -### Alternative way - -If you want to have a bit more control - or you don't want to use `pipx`, -just create a virtual environment first and then install `MUSE-OS`. - -Although not strictly necessary, **creating a virtual environment is highly recommended**: -it will isolate users and developers from changes occuring on their operating system, -and from conflicts between python packages. It ensures reproducibility from day to day. - -There are several ways of creating a virtual environment - below we list two of them. -Regardless of the method used, **once it has been created and activated**, you can install -`MUSE-OS` within using: - -```bash -python -m pip install MUSE-OS -``` - -And then use it by invoking `muse` with the relevant input arguments. - -#### Creating a virtual environment using `conda` - -Create a virtual environment including python with: - -```bash -conda create -n muse_env python=3.9 -``` - -Activate the environment with: - -```bash -conda activate muse_env -``` - -Later, to recover the system-wide "normal" python, deactivate the environment with: - -```bash -conda deactivate -``` - -#### Creating a virtual environment using `venv` - -Create a virtual environment with: - -```bash -python -m pip install venv -python -m venv muse_env -``` - -Activate the environment with: - -```powershell -# In Powershell -muse_env\Scripts\Activate.ps1 - -# In Linux/MacOS -source muse_env/bin/activate -``` - -Later, to recover the system-wide "normal" python, deactivate the environment with: - -```bash -deactivate -``` +- Recommended installation instructions +- Instructions for developers ## Usage @@ -106,53 +26,6 @@ Once installed, users can: - run `muse --help` to get a description of the command-line arguments, including the name of any additional models provided with MUSE. -## Development - -It is strongly recommened to use a virtual environment, as above. The simplest approach is to -first download the muse code with: - -```bash -> git clone https://github.com/SGIModel/MUSE_OS.git -``` - -```bash -cd MUSE_OS -# Create virtual environment - for development, this is typically called ".venv" -# Activate virtual environment. Finally, install muse: -python -m pip install -e ."[dev,doc]" -``` - -Please note the quotation marks. The downloaded code can then be modified. The changes will be -automatically reflected in the environment. - -To ensure the consistency of the code with other developers, install the pre-commit hooks with: - -```bash -python -m pip install pre-commit -pre-commit install -``` - -This will ensure that a series of quality assurance tools are run with every commit you make. - -In the developing phase, MUSE can also be used to run test cases to check that the model would reproduce expected results from a defined set of input data. Tests can be run with the command [pytest](https://docs.pytest.org/en/latest/), from the testing framework of the same name. - -The documentation can be built with: - -```bash -python -m sphinx -b html docs docs/build -``` - -The main page for the documentation can then be found at -`docs\\build\\html\\index.html` (or `docs/build/html/index.html` on Mac and Linux). -The file can viewed from any web browser. - -[vscode](https://code.visualstudio.com/) users will find that the repository is setup -with default settings file. Users will still need to [choose the virtual -environment](https://code.visualstudio.com/docs/python/environments#_select-and-activate-an-environment), -or conda environment where to run the code. This will change the `.vscode/settings.json` -file and add a user-specific path to it. Users should try and avoid commiting changes to -`.vscode/settings.json` indiscriminately. - -## Copyrigh +## Copyright Copyright © 2023 Imperial College London diff --git a/docs/figures/disable_python_alias.png b/docs/figures/disable_python_alias.png new file mode 100644 index 000000000..7166b69ff Binary files /dev/null and b/docs/figures/disable_python_alias.png differ diff --git a/docs/figures/launch_power_shell.png b/docs/figures/launch_power_shell.png new file mode 100644 index 000000000..4308adebd Binary files /dev/null and b/docs/figures/launch_power_shell.png differ diff --git a/docs/figures/visual-studio-installation.png b/docs/figures/visual-studio-installation.png deleted file mode 100644 index 1e529723d..000000000 Binary files a/docs/figures/visual-studio-installation.png and /dev/null differ diff --git a/docs/index.rst b/docs/index.rst index 163aff8bc..b7a5c93b1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,10 +10,11 @@ ModUlar energy system Simulation Environment: MUSE .. toctree:: :maxdepth: 2 :caption: Contents: + :numbered: :titlesonly: Glossary - Installing MUSE + Installing MUSE Running MUSE MUSE Overview Key MUSE Components diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 000000000..629950778 --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,420 @@ + +.. contents:: + +Installing MUSE +=============== + +Recommended installation +------------------------ + +To help you installing MUSE in your system we will follow these steps: + +- `Launching a terminal`_: Needed to both install and run MUSE. +- `Installing a compatible Python version`_: At the moment, MUSE works with Python 3.8 and 3.9. +- `Installing pipx`_: A Python application manager that facilitates installing, keeping applications updated and run them in their own isolated environments. +- `Installing MUSE itself`_ + +In the following sections, we will guide you step by step in configuring your system so it can run MUSE. At the end, we include alternative ways of installing MUSE if this method does not work for any reason, for advanced users and for developers of MUSE. + +.. note:: + + The next sections will explain in detail the appropriate steps as well as commenting on possible caveats. **We strongly encourage you to read through the sections below** to understand what these steps entitle, but in the end, what we are going to do to install MUSE is the following: + + - Open a terminal + - Install `pyenv `_ (Linux and MacOS) or `pyenv-win `_ (Windows) and make sure it works. + - Run the following commands in the terminal: + + .. code-block:: + + pyenv install 3.9.13 + pyenv shell 3.9.13 + python -m pip install pipx + python -m pipx ensurepath + python -m pipx install muse-os + + - After this, MUSE will be available to use system wide simply by invoking ``muse`` in the terminal, for example ``muse --model default``. + + + +Launching a terminal +~~~~~~~~~~~~~~~~~~~~ + +All operative systems have a Terminal application that let you run commands. You will need to use it extensively when using MUSE, so we strongly suggest you get familiar with it. For now, let's just figure out how to launch it: + +- **Linux**: Depending on the distribution, you might have a shortcut in your tasks bar already or it should be easily found in the menu. Look for ``Console`` or ``Terminal`` to lunch the application. +- **MacOS**: Press ``Super key + Space`` to open the search box. There, type ``Terminal`` and press ``Enter``. +- **Windows**: Windows comes with a couple of options. We will be using ``Windows PowerShell``. Press the ``Windows key`` and start typing ``PowerShell``. When the application shows up, click to on it. + + .. image:: figures/launch_power_shell.png + :width: 500 + :align: center + :alt: Launching Windows PowerShell from the menu + +Once you have launched the Terminal, the window that opens will show the command prompt, where we will input all the commands form now on. The following are a couple of examples of what it looks like, typically, but it might be a bit different in your system depending on how it is configured: + +- Linux and MacOS Terminal: + +.. code-block:: bash + + your_user_name@computer_name:~$ + +- Windows PowerShell: + +.. code-block:: powershell + + PS C:\Users\your_user_name> + +.. note:: + + For simplicity, we will be excluding the command prompt in the following sections whenever we indicate that a command should be executed in the terminal. + +Installing a compatible Python version +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +MUSE needs Python to run but, for now, it only works with versions 3.8 and 3.9, so the next step is to install a suitable version of Python. + +.. note:: + + Windows users should disable the alias for Python that comes by default with Windows and that will try to install Python from the Microsoft Store everytime we write ``python`` in the terminal. To do so, press the ``Windows key`` and start typing ``alias``, when it shows up, click in ``Manage app execution aliases``. In the window that opens, disable all the entries related to Python, like in the image. + + .. image:: figures/disable_python_alias.png + :width: 400 + :align: center + :alt: Screen to disable the Python aliases defined by Windows. + +.. note:: + + If you already have a Python version installed from the Microsoft Store, you might have a ``py`` command that will launch Python in the terminal. That Python Launcher will use a Microsoft Stored-installed version of Python. Unless any of those versions, under the control of Microsoft and their autoupdating schedule, happen to be compatible with MUSE, we advise against using the launcher and follow the instructions below, which will give you more control on what is exactly being run and how MUSE is being installed. + +The first thing will be to check if you already have a suitable python version installed. Open a terminal and run: + +.. code-block:: bash + + python --version + +If the output is ``Python 3.8.X`` or ``Python 3.9.X``, where ``X`` is any number, then you have a version of Python compatible with MUSE and you can skip this section altogether. Move to `Installing pipx`_. In any other case, keep reading. + +There are multiple ways of installing Python, as well as multiple distributions. Here we have opted for the one that we believe is simplest, requires the smallest downloads and gives the maximum flexibility: using ``pyenv``. + +.. note:: + + If you have Anaconda Python installed, then you can use it instead of ``pyenv`` to create an environment with a suitable Python version. Go to section `Creating a conda virtual environment`_ and jump to `Installing pipx`_ when it is completed. + +Installing ``pyenv`` +^^^^^^^^^^^^^^^^^^^^ + +`pyenv `_ (`pyenv-win `_ for Windows) is a tool that lets you install and manage different python versions. It is small, unobtrusive and self-contained, and it is available for the three operative systems. + +To install it, follow these steps: + +- **Linux**: In this case, you will need to clone the GitHub repository using ``git``. Most Linux distributions come with ``git`` installed, so this should work out of the box: + + .. code-block:: bash + + git clone https://github.com/pyenv/pyenv.git ~/.pyenv + + Then, complete the setup by adding ``pyenv`` to your profile, so the executable can be found. `Check the instructions in the official webpage `_. + +- **MacOS**: The simplest option is to use Homebrew: + + .. code-block:: bash + + brew update + brew install pyenv + + Then, complete the setup by adding ``pyenv`` to your profile, so the executable can be found. `Check the instructions in the official webpage `_. + +- **Windows**: ``pyenv-win`` is a separate project but it has the same functionality and it is also simpler to setup. Just run the following command and you should be ready to go: + + .. code-block:: powershell + + Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/pyenv-win/pyenv-win/master/pyenv-win/install-pyenv-win.ps1" -OutFile "./install-pyenv-win.ps1"; &"./install-pyenv-win.ps1" + + .. note:: + + If you are getting any ``UnauthorizedAccess`` error, then start Windows PowerShell with the “Run as administrator” option (see figure above) and run: + + .. code-block:: powershell + + Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine + + Finally open a normal PowerShell and re-run the above installation command. + +After completing the above steps, you will need to close the terminal and re-open it again. After that, to check if things work run: + +.. code-block:: bash + + pyenv --version + +You should get something similar to: + +.. code-block:: output + + pyenv 3.1.1 + +Actually installing Python +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +With ``pyenv`` installed and correctly configured, it is now easy to install any Python version we want. To see the versions available run: + +.. code-block:: bash + + pyenv install -l + +You should see a very long list of versions to choose from. Let's install the latest version of the 3.9 family: + +.. code-block:: bash + + pyenv install 3.9.13 + +The command will take a minute or two to complete, depending on your internet connection, and show an output similar to the following (this is just an example for Windows): + +.. code-block:: output + + :: [Info] :: Mirror: https://www.python.org/ftp/python + :: [Downloading] :: 3.9.13 ... + :: [Downloading] :: From https://www.python.org/ftp/python/3.9.13/python-3.9.13-amd64.exe + :: [Downloading] :: To C:\Users\your_username\.pyenv\pyenv-win\install_cache\python-3.9.13-amd64.exe + :: [Installing] :: 3.9.13 ... + :: [Info] :: completed! 3.9.13 + +Now, we have a new Python version in our system, but it is still not available (if you run ``python --version`` you will get the same result as before). There are two options moving forward: + +- If you want to set it as the global python version, available system wide (only do this if you really want to set is as your main Python!) run: + + .. code-block:: bash + + pyenv global 3.9.13 + +- If you just want it momentarily to install MUSE run instead the following command: + + .. code-block:: bash + + pyenv shell 3.9.13 + +In both cases, if you run ``python --version`` afterwards, you should get ``Python 3.9.13``. + +Installing ``pipx`` +~~~~~~~~~~~~~~~~~~~ + +Next we need to install ``pipx``, a Python application manager that facilitates installing, keeping applications updated and run them in their own isolated environments. We could skip this step and install MUSE directly, but that will risk to have conflicting dependencies in the future if you install any other application, breaking your MUSE installation, and we do not want that to happen. + +The installation instructions for ``pipx`` can be found in the `official webpage `_ specific for the three operative systems. The following instructions, however, should work for the three cases: + +.. code-block:: bash + + python -m pip install pipx + python -m pipx ensurepath + +Make sure you run these commands with a compatible Python version, as described in the previous section. If for whatever reason, this does not work, follow the system specific instructions in the webpage. + +Installing MUSE itself +~~~~~~~~~~~~~~~~~~~~~~ + +With all the system prepared, installing MUSE is the easiest part: + +.. code-block:: bash + + python -m pipx install muse-os + +As above, make sure you run this command with the appropriate Python version. + +And that is all! Now, MUSE should be available system wide simply by running ``muse`` in the terminal. For example, open a new terminal and run: + +.. code-block:: bash + + muse --model default + +This will run a default, example model, completing after reaching year 2050. The following are the last few lines of the simulation: + +.. code-block:: + + ... + -- 2023-08-02 09:11:50 - muse.sectors.sector - INFO + Running gas for year 2050 + + -- 2023-08-02 09:11:50 - muse.interactions - INFO + Net new_to_retro of 1 interactions interacting via transfer + + -- 2023-08-02 09:11:50 - muse.hooks - INFO + Computing initial_asset_transform: default + + -- 2023-08-02 09:11:50 - muse.hooks - INFO + Computing initial_asset_transform: clean + + -- 2023-08-02 09:11:50 - muse.demand_share - INFO + Computing demand_share: default + + -- 2023-08-02 09:11:51 - muse.production - INFO + Computing production: max + + -- 2023-08-02 09:11:51 - muse.production - INFO + Computing production: max + + -- 2023-08-02 09:11:51 - muse.production - INFO + Computing production: share + + -- 2023-08-02 09:11:51 - muse.mca - INFO + Finish simulation year 2050! + + +Alternative installation instructions +------------------------------------- + +If you don't want to use ``pyenv`` or ``pipx``, or if you are having trouble with those tools, there are a couple of alternatives. + +Installing Anaconda Python +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +We have chosen ``pyenv`` above because it is extremely lightweight and unobtrusive with your operative system. However, you might want to consider a more fully fledged Python distribution like Anaconda, specially if your work involved non-python packages or a lot of data science and machine learning tools. + +Regardless of the reason, if you want to follow this route just go to the official `Anaconda webpage `_ and download and install a version appropriate for your operative system. Do not worry about the Python version as ``conda`` will let you choose that when creating a virtual environment. + +The installer should guide you step by step on the process of installing Anaconda and configuring your system to use it as your Python installation. + +Creating virtual environments +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Although not strictly necessary, **creating a virtual environment is highly recommended** regardless of how you installed Python. It will isolate users and developers from changes occurring on their operating system, and from conflicts between python packages and it ensures reproducibility from day to day. + +Using ``pipx`` ensures that each application it installs has its own virtual environment, running it under the hood. However, you can explicitly create and manage the virtual environment if you prefer. + +Creating a ``conda`` virtual environment +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This option is available only if you installed Anaconda Python. Depending on the settings you used when installing Anaconda and your operative system, you might have ``conda`` available in your normal terminal or you might need to use the Anaconda Prompt. + +``conda`` not only lets you create a virtual environment but also selecting which python version to use within, independently of the version of Anaconda Python installed, which means it can be an alternative to ``pyenv`` if it happens that you already have Anaconda installed in your system. + +To create an environment called ``muse_env`` run: + +.. code-block:: bash + + conda create -n muse_env python=3.9 + +Now, you can activate the environment with: + +.. code-block:: bash + + conda activate muse_env + +Later, to recover the system-wide "normal" python, deactivate the environment with: + +.. code-block:: bash + + conda deactivate + +Creating a virtual environment with ``venv`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Modern Python versions, regardless of their origin, come with a built in tool to create virtual environments, ``venv``. However, contrary to ``conda`` it does not let you select the version of Python that will be used - it will be the same one you are using to create the environment. Therefore, you still need to make sure your version of Python is compatible with MUSE. You can check it with ``python --version``. + +Another caveat is that the virtual environment will be created in a specific folder, so whenever you want to use it in the future, you will need to remember in what folder it was created and activate the environment from there. + +You can create a virtual environment with: + +.. code-block:: bash + + python -m venv venv + +And then you activate the environment with: + +- Linux: + + .. code-block:: bash + + source venv/bin/activate + +- MacOS: + + .. code-block:: zsh + + . venv/bin/activate + +- Windows: + + .. code-block:: powershell + + venv\Scripts\Activate.ps1 + +Later, to recover the system-wide "normal" python, deactivate the environment with: + +.. code-block:: bash + + deactivate + +Installing MUSE in a virtual environment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Regardless of the method used, **once it has been created and activated**, you can install ``MUSE`` within using: + +.. code-block:: bash + + python -m pip install muse-os + +And then use it by invoking ``muse`` with the relevant input arguments. Keep in mind that, contrary to using ``pipx``, in this case **you will need to manually activate the environment every time you want to use MUSE**. + +Instructions for development +---------------------------- + +Developers of MUSE will need to have the version control tool ``git`` installed in their system and be familiar with its usage. The `Introduction to Git and GitHub for software development `_ course created by `Imperial RSE Team `_ can be a good place to start. + +Installing MUSE source code in editable mode +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Once you have ``git`` in your system, clone MUSE repository with: + +.. code-block:: bash + + git clone https://github.com/SGIModel/MUSE_OS.git + +Then, we will create a virtual environment, either using ``conda`` or using ``venv`` as explained above, and install MUSE within the environment: + +.. code-block:: bash + + cd MUSE_OS + # 1- Create virtual environment + # 2- Activate virtual environment + # 3- Finally, install MUSE in editable mode with: + python -m pip install -e .[dev,doc] + +Depending on your system, you might need to add quotation marks around ``[dev,doc]`` as in ``"[dev,doc]"``. This will install MUSE and all the dependencies required for its development. The downloaded code can be modified and the changes will be automatically reflected in the environment. + +Installing pre-commit hooks +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To ensure the consistency of the code with other developers, install the pre-commit hooks, which will run a series of checks whenever there is a new commit: + +.. code-block:: bash + + python -m pip install pre-commit + pre-commit install + +Running tests +~~~~~~~~~~~~~ + +In the developing phase, MUSE can also be used to run test cases to check that the model would reproduce expected results from a defined set of input data. Tests can be run with the command [pytest](https://docs.pytest.org/en/latest/), from the testing framework of the same name. + +Within the ``MUSE-OS`` directory, just run: + +.. code-block:: bash + + python -m pytest + +Building the documentation +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The documentation can be built with Sphinx: + +.. code-block:: bash + + python -m sphinx -b html docs docs/build + +This command will use ``pandoc`` under the hood, which might not be available in your system. If that were the case, install it `following the instructions in the official webpage `_. + +The main page for the documentation can then be found at ``docs/build/html/index.html`` and the file can viewed from any web browser. + +Configuring VSCode +~~~~~~~~~~~~~~~~~~ + +`VSCode `_ users will find that the repository is setup with default settings file. Users will still need to `choose the virtual environment `_, or conda environment where to run the code. This will change the ``.vscode/settings.json`` file and add a user-specific path to it. Users should try and avoid committing changes to ``.vscode/settings.json`` indiscriminately. diff --git a/docs/installing-muse.rst b/docs/installing-muse.rst deleted file mode 100644 index 320821fc2..000000000 --- a/docs/installing-muse.rst +++ /dev/null @@ -1,153 +0,0 @@ -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. - To download any Visual Studio product, users should first log in with their Visual Studio account. - Either a Visual Studio Subscription, or a free account can be used by clicking on “Create a new Microsoft account” on the login page. - - After login on the Visual Studio account, https://visualstudio.microsoft.com/downloads/ the VisualStudioSetup.exe could be downloaded, selecting the latest - - 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. - - #. Install latest Visual Studio from the following link: https://visualstudio.microsoft.com/downloads/ - - #. Select the “Visual Studio Community” version. Click on “Download” and save the executable vs_Commmunity.exe. - - #. Install Visual Studio by selecting the default options. You may be asked to reboot your computer to complete the installation. - - #. Download the Microsoft Visual C++ Build Tools from the following link: https://visualstudio.microsoft.com/downloads. - - #. Please select the “Build Tools for Visual Studio 2019 (version 16.9)”. Click on download. Save the vs_BuildTools.exe. - - #. Run the installer - - #. Select: Workloads → Desktop development with C++. - - #. 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. - - - Earlier versions of Visual Studio BuildTools than the latest can be downloaded at https://visualstudio.microsoft.com/vs/older-downloads selecting the desired version of the VisualStudio installer and the corresponding VuildTools version. - - For the 2019 version, the installation screen should look similar to the following: - - .. image:: figures/visual-studio-installation.png - - For further information, see this link: __ - - - - .. __: https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2019 - -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.8, 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: - -.. code-block:: bash - - python -m pip install --user git+https://github.com/SGIModel/MUSE_OS - -It should now be possible to run muse. Again, this can be done in the anaconda prompt as follows: - -.. code-block:: bash - - 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 :ref:`installation-devs`. - -.. _installation-devs: - - -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: - -.. code-block:: bash - - conda create -n muse python=3.8 - -Activate the environment with: - -.. code-block:: bash - - conda activate muse - -Later, to recover the system-wide "normal" python, deactivate the environment with: - -.. code-block:: bash - - conda deactivate - -The simplest approach is to first download the muse code with `git`_: - -.. code-block:: bash - - git clone https://github.com/SGIModel/MUSE_OS.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: - -.. code-block:: bash - - # On Linux and Mac - cd muse - conda activate muse - python -m pip install -e ".[dev,doc]" - - # On Windows - dir muse - conda activate muse - python -m pip install -e ".[dev,doc]" - -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: - -.. code-block:: bash - - 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. - -.. _anaconda distribution: https://docs.anaconda.com/free/anaconda/index.html - -.. _anaconda prompt: - https://docs.anaconda.com/anaconda/user-guide/getting-started/#write-a-python-program-using-anaconda-prompt-or-terminal - -.. _anaconda virtual environment: https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html - -.. _pytest: https://docs.pytest.org/en/latest/ - -.. _git: https://git-scm.com/ - -.. __: http://try.github.io/ - - diff --git a/docs/user-guide/index.rst b/docs/user-guide/index.rst index bca7b8b31..38050fcf2 100644 --- a/docs/user-guide/index.rst +++ b/docs/user-guide/index.rst @@ -10,7 +10,6 @@ We recommend following the tutorials step by step, as the files build on the pre .. toctree:: :maxdepth: 1 :caption: Tutorial contents: - :numbered: add-solar add-agent