.. _install:

*************************
Installation
*************************

ANDES can be installed in Python 3.6+.
Please follow the installation guide carefully.

Environment
===========

Setting Up Miniconda
--------------------
We recommend the Miniconda distribution that includes the conda package manager and Python.
Downloaded and install the latest Miniconda (x64, with Python 3)
from https://conda.io/miniconda.html.

Step 1: Open terminal (on Linux or maxOS) or `Anaconda Prompt` (on Windows, **not the cmd
program!!**).
Make sure you are in a conda environment - you should see ``(base)`` prepended to the
command-line prompt, such as ``(base) C:\Users\user>``.

Create a conda environment for ANDES (recommended)

.. code:: bash

     conda create --name andes python=3.7

Activate the new environment with

.. code:: bash

     conda activate andes

You will need to activate the ``andes`` environment every time in a new Anaconda Prompt or
shell.

Step 2: Add the ``conda-forge`` channel and set it as default

.. code:: bash

     conda config --add channels conda-forge
     conda config --set channel_priority flexible

If these steps complete without an error, continue to `Install Andes`_.

Existing Python Environment (Advanced)
--------------------------------------
This is for advanced user only and is **not recommended on Microsoft Windows**.
Please skip it if you have set up a Conda environment.

Instead of using Conda, if you prefer an existing Python environment,
you can install ANDES with `pip`:

.. code:: bash

      python3 -m pip install andes

If you see a `Permission denied` error, you will need to
install the packages locally with `--user`

Install ANDES
=============

ANDES can be installed in the user mode and the development mode.

- If you want to use ANDES without modifying the source code, install it in the `User Mode`_.
- If you want to develop models or routine, install it in the `Development Mode`_.

User Mode
---------
.. warning ::
    Please skip this section and install ANDES in the `Development Mode`_
    if you want to modify ANDES code or receive unreleased development
    updates.

The User Model installation will install the latest stable version.
In the Anaconda environment, run

.. code:: bash

    conda install andes

You will be prompted to confirm the installation,

This command installs ANDES into the active environment, which should be called ``andes`` if
you followed all the above steps.

.. note::
    To use ``andes``, you will need to activate the ``andes`` environment every time in a new Anaconda Prompt or
    shell.


Development Mode
----------------
This is for users who want to hack into the code and, for example, develop new models or routines.
The usage of ANDES is the same in development mode as in user mode.
In addition, changes to source code will be reflected immediately without re-installation.

Step 1: Get ANDES source code

As a developer, you are strongly encouraged to clone the source code using ``git``
from either your fork or the original repository:

.. code:: bash

    git clone https://github.com/cuihantao/andes

In this way, you can easily update to the latest source code using ``git``.

Alternatively, you can download the ANDES source code from
https://github.com/cuihantao/andes and extract all files to the path of your choice.
Although this will work, this is not recommended since tracking changes and pushing back code
would be painful.

Step 2: Install dependencies

In the Anaconda environment, use ``cd`` to change directory to the ANDES root folder.

Install dependencies with

.. code:: bash

    conda install --file requirements.txt
    conda install --file requirements-dev.txt

Step 3: Install ANDES in the development mode using

.. code:: bash

      python3 -m pip install -e .

Note the dot at the end. Pip will take care of the rest.

Updating ANDES
==============

Regular ANDES updates will be pushed to both ``conda-forge`` and Python package index.
It is recommended to use the latest version for bug fixes and new features.
We also recommended you to check the :ref:`ReleaseNotes` before updating to stay informed
of changes that might break your downstream code.

Depending you how you installed ANDES, you will use one of the following ways to upgrade.

If you installed it from conda (most common for users), run

.. code:: bash

    conda install -c conda-forge --yes andes

If you install it from PyPI (namely, through ``pip``), run

.. code:: bash

    python3 -m pip install --yes andes

If you installed ANDES from source code (in the `Development Mode`_),
and the source was cloned using ``git``,
you can use ``git pull`` to pull in changes from remote. However, if your source
code was downloaded, you will have to download the new source code again and manually
overwrite the existing one.

In rare cases, after updating the source code, command-line ``andes`` will complain
about missing dependency. If this ever happens, it means the new ANDES has introduced
new dependencies. In such cases, reinstall andes in the development mode to fix.
Change directory to the ANDES source code folder that contains ``setup.py`` and run

.. code:: bash

    python3 -m pip install -e .

Performance Packages
====================
.. note::

    Performance packages can be safely skipped and will not affect the
    functionality of ANDES.

KVXOPT
------

KVXOPT is a fork of the CVXOPT with KLU by Uriel Sandoval (@sanurielf).
KVXOPT interfaces to KLU, which is
roughly 20% faster than UMFPACK for circuit simulations based on our testing.

KVXOPT contains inplace add and set functions for sparse matrix
contributed by CURENT.
These inplace functions significantly speed up large-scale system simulations.

To install ``KVXOPT`` run

.. code:: bash

      python -m pip install kvxopt