Installation — mosaik 2.0a1 documentation

# Installation

This guide contains detailed installation instructions for Linux, OS X and Windows.

## Linux

This guide is based on (K)ubuntu 14.04 Trusty Tahr, 64bit (beta 2).

Mosaik and the demo scenario require Python >= 3.3. Ubuntu ships with Python 3.4, so everything is okay.

1. We also need pip, a package manager for Python packages, and virtualenv, which can create isolated Python environments for different projects:

       $ wget https://raw.github.com/pypa/pip/master/contrib/get-pip.py
       $ sudo python get-pip.py
       $ sudo pip install -U virtualenv

   Optionally, you can also install virtualenvwrapper which makes working with virtualenv easier. It’s not necessary if you just want to get the demo running, but very useful if you keep developing with Python.

2. Now we need to create a virtual environment for mosaik and its dependencies. The common location for venvs is under `~/.virtualenvs/`:

       $ virtualenv -p /usr/bin/python3 ~/.virtualenvs/mosaik
       $ source ~/.virtualenvs/mosaik/bin/activate

   Your command line prompt should now start with “(mosaik)” and roughly look like this: `(mosaik)user@kubuntu:~$`.

3. The final step is to install mosaik:

       (mosaik)$ pip install --pre mosaik

   Mosaik should now be installed successfully.

### Running the demo

Mosaik alone is not very useful (because it needs other simulators to perform a simulation), so we also provide a small demo scenario and some simple simulators as well as a mosaik binding for PYPOWER.

1. PYPOWER requires NumPy and SciPy. You can a) use the packages shipped with Ubuntu (faster, easier, but they may be outdated, recommended if you just want to run the demo scenario) or b) compile them on your own (a bit more complicated, takes longer, recommended for development). In both cases, you also need to install Mercurial and Git:

   1. We use apt-get to install NumPy and SciPy (as well as Mercurial and Git). By default, venvs are isolated from globally installed packages. To make them visible, we also have to recreate the venv and set the `--system-site-packages` flag:

          $ sudo apt-get install mercurial git python3-numpy python3-scipy
          $ rm -rf ~/.virtualenvs/mosaik
          $ virtualenv -p /usr/bin/python3 --system-site-packages ~/.virtualenvs/mosaik
          $ source ~/.virtualenvs/mosaik/bin/activate

   2. In order to compile NumPy and SciPy, we need to install some build dependencies (and Mercurial and Git). We then build binary wheel packages that we can later reuse without re-compiling everything. We’ll store these wheels in `~/wheelhouse/`:

          $ sudo apt-get instal mercurial git build-essential python3-dev gfortran libatlas-dev libatlas-base-devl
          $ source ~/.virtualenvs/mosaik/bin/activate
          (mosaik)$ pip install wheel
          (mosaik)$ pip wheel numpy
          (mosaik)$ pip install wheelhouse/numpy-1.8.1-cp34-cp34m-linux_x86_64.whl
          (mosaik)$ pip wheel scipy
          (mosaik)$ pip install wheelhouse/scipy-0.13.3-cp34-cp34m-linux_x86_64.whl

2. You can now clone the mosaik-demo repository into a folder where you store all your code and repositories (we’ll use `~/Code/`):

       (mosaik)$ mkdir ~/Code
       (mosaik)$ hg clone https://bitbucket.org/mosaik/mosaik-demo ~/Code/mosaik-demo

3. Now we only need to install all requirements (mosaik and the simulators) and can finally run the demo:

       (mosaik)$ cd ~/Code/mosaik-demo/
       (mosaik)$ pip install -r requirements.txt
       (mosaik)$ python demo.py

   If no errors occur, you can now open the web visualization. You can click the nodes of the topology graph to show a timeline of their values. You can also drag them around to rearrange them.

   You can cancel the simulation by pressing `Ctrl-C`.

## OS X

This guide is based on OS X 10.9 Mavericks.

1. Mosaik and the demo scenario require Python >= 3.3. OS X only ships with some outdated versions of Python, so we need to install a recent Python 2 and 3 first. The recommended way of doing this is with homebrew. Therefore, we need to open Terminal and execute the following command:

       $ ruby -e "$(curl -fsSL https://raw.github.com/Homebrew/homebrew/go/install)"

   The homebrew installer may ask you to install the command line developer tools for “xcode-select”. Install them. When you are done, go back to the terminal and press `Enter` so that the installer continues.

   If this doesn’t work for you, you’ll find more detailed instructions in the homebrew wiki.

   Once the installation is successful, we can install `python` and `python3`:

       $ brew install python python3

   This will also install the Python package manager pip.

2. Furthermore, we need virtualenv which can create isolated Python environments for different projects:

       $ pip install -U virtualenv

   Optionally, you can also install virtualenvwrapper which makes working with virtualenv easier. It’s not necessary if you just want to get the demo running, but very useful if you keep developing with Python.

3. Now we need to create a virtual environment for mosaik and its dependencies. The common location for venvs is under `~/.virtualenvs/`:

       $ virtualenv -p /usr/local/bin/python3 ~/.virtualenvs/mosaik
       $ source ~/.virtualenvs/mosaik/bin/activate

   Your command line prompt should now start with “(mosaik)” and roughly look like this: `(mosaik)user@macbook:~$`.

4. The final step is to install mosaik:

       (mosaik)$ pip install --pre mosaik

   Mosaik should now be installed successfully.

### Running the demo

Mosaik alone is not very useful (because it needs other simulators to perform a simulation), so we also provide a small demo scenario and some simple simulators as well as a mosaik binding for PYPOWER.

1. To clone the demo repository, we need to install Mercurial. In order to compile NumPy and SciPy (which are required by PYPOWER) we also need to install gfortran. You should deactivate the venv for this:

       (mosaik)$ deactivate
       $ brew install hg gfortran

2. For NumPy and SciPy we build binary wheel packages that we can later reuse without re-compiling everything. We’ll store these wheels in `~/wheelhouse/`:

       $ source ~/.virtualenvs/mosaik/bin/activate
       (mosaik)$ pip install wheel
       (mosaik)$ pip wheel numpy
       (mosaik)$ pip install wheelhouse/numpy-1.8.1-cp34-cp34m-macosx_10_9_x86_64.whl
       (mosaik)$ pip wheel scipy
       (mosaik)$ pip install wheelhouse/scipy-0.13.3-cp34-cp34m-macosx_10_9_x86_64.whl

2. You can now clone the mosaik-demo repository into a folder where you store all your code and repositories (we’ll use `~/Code/`):

       (mosaik)$ mkdir ~/Code
       (mosaik)$ hg clone https://bitbucket.org/mosaik/mosaik-demo ~/Code/mosaik-demo

3. Now we only need to install all requirements (mosaik and the simulators) and can finally run the demo:

       (mosaik)$ cd ~/Code/mosaik-demo/
       (mosaik)$ pip install -r requirements.txt
       (mosaik)$ python demo.py

   If no errors occur, you can now open the web visualization. You can click the nodes of the topology graph to show a timeline of their values. You can also drag them around to rearrange them.

   You can cancel the simulation by pressing `Ctrl-C`.

## Windows

Note

There is currently no one-click-exe-installer for mosaik. This is due to its early development stage. The installion process will get easier in the future, though.

This guide is based on Windows 7, 64bit.

1. Mosaik and the demo scenario require Python >= 3.3. By default, it will offer you a 32bit installer. You can find the Windows x86-64 MSI installer here.

   1. When the download finished, double-click the installer.
   2. Select Install for all users and click Next >.
   3. The default installation path is okay. Click Next >.
   4. In the Customize Python page, click on the Python node and select Entire feature will be installed on local hard drive. Make sure that Add python.exe to Path is enabled. Click Next >.
   5. When Windows asks you to allow the installation, allow the installation. Wait. Click Finish.

   This also installed Python package manager pip.

2. We also need virtualenv which can create isolated Python environments for different projects.

   Open a terminal window: Press the `Windows` key (or click on the start menu) and enter `cmd`. Press `Enter`. Your terminal Prompt should look like `C:\Users\yourname>`. Execute the following command to install virtualenv:

       C:\Users\yourname> pip install -U virtualenv

3. Now we need to create a virtual environment for mosaik and its dependencies. The common location for venvs is under `Envs/` in your users directory:

       C:\Users\yourname> virtualenv -p C:\Python34\python.exe Envs\mosaik
       C:\Users\yourname> Envs\mosaik\Scripts\activate.bat

   Your command line prompt should now start with “(mosaik)” and roughly look like this: `(mosaik) C:\Users\yourname>`.

4. The final step is to install mosaik:

       (mosaik) C:\Users\yourname> pip install --pre mosaik

   Mosaik should now be installed successfully.

### Running the demo

Mosaik alone is not very useful (because it needs other simulators to perform a simulation), so we also provide a small demo scenario and some simple simulators as well as a mosaik binding for PYPOWER.

1. PYPOWER requires NumPy and SciPy. Christoph Gohlke provides installers for them (NumPy, SciPy). Select the appropriate files for your system (32bit or 64bit, Python version), e.g., numpy‑MKL‑1.8.1.win‑amd64‑py3.4.exe and scipy‑0.13.3.win‑amd64‑py3.4.exe.

   Download them into your downloads folder and install them via the following commands:

       (mosaik) C:\Users\yourname> easy_install Downloads\numpy-MKL-1.8.1.win-amd64-py3.4.exe
       (mosaik) C:\Users\yourname> easy_install Downloads\scipy-0.13.3.win-amd64-py3.4.exe

2. Download and install Mercurial and Git (Git is only required temorary and won’t be necessary in the future). During the installation of Git select Run Git from the Windows Command Prompt.

   Restart the command prompt and activate the virtualenv again:

       C:\Users\yourname> Envs\mosaik\Scripts\activate.bat

2. Clone the demo repository:

       (mosaik)C:\Users\yourname> hg clone https://bitbucket.org/mosaik/mosaik-demo

3. Now we only need to install all requirements (mosaik and the simulators) and can finally run the demo:

       (mosaik)C:\Users\yourname> cd mosaik-demo
       (mosaik)C:\Users\yourname> pip install -r requirements.txt
       (mosaik)C:\Users\yourname> python demo.py

   An exception may be raised at the end of the installation, but as long as before that exception there was the output Successfully installed PYPOWER mosaik-csv mosaik-householdsim ..., everything is okay.

   You can now open the web visualization. You can click the nodes of the topology graph to show a timeline of their values. You can also drag them around to rearrange them.

   You can cancel the simulation by pressing `Ctrl-C`. More exceptions may be raised. No problem. :-)