Installing VICE

On PyPI we provide pre-compiled binary installers and source distributions for released versions of VICE. To install the latest version, we recommend simply running

$ python -m pip install vice [--user]

from the command line. Users should add the --user flag if they do not have administrative privileges on their current machine; this will install VICE to their ~/.local directory. To compile and install VICE from source using PyPI, simply specify that you do not want to use the binary using the --no-binary flag:

$ python -m pip install vice [--user] --no-binary :all:

The option :all: above tells pip to install all of the packages in the current call to pip install without binaries; when installing multiple packages, this value can be specified as a comma-separated list. Further details on the --no-binary option can be found in the associated documentation for the pip install command. Rather than downloading a pre-compiled binary, pip will download the source distribution provided on PyPI and compile and install VICE on your machine. pip should also conduct an installation using the source distribution automatically in the event that a pre-compiled binary is unavailable for a user’s operating system and CPU architecture.

Additionally, previous versions available on PyPI can be installed by simply specifying the version number:

$ python -m pip install vice==<version number> [...]

Designed for systems with a Unix kernel, VICE does not function within a windows environment. Windows users should therefore install VICE within the Windows Subsystem for Linux (WSL). Provided that the call to pip is ran from within WSL, the pre-compiled binary installer from PyPI should install VICE properly. A manual installation on a windows machine must also be ran within WSL.

For the current version, we provide pre-compiled binaries for Python versions 3.6-3.10 on computers with an x86_64 CPU architecture running Mac OS and Linux operating systems. We do not provide pre-compiled binaries for CPU architectures other than x86_64. This includes Linux computers with Aarch64 hardware as well as the new ARM64 Apple Silicon computers (i.e. the M1 chip). At present, the developers do not have the resources necessary to pre-compile VICE for these machines, we apologize for the inconvenience. Although VICE can be installed and ran on 32-bit hardware (e.g. i686 CPUs), we strongly discourage running VICE on such machines.

Users who have or would like to modify VICE’s source code must conduct a manual installation. This also applies to users who would like to install a version of VICE that is still under development (these can be found on various branches of its GitHub repository) as well as for versions of python still under development.

Although it is generally not advised to mix package managers, this is not a concern for VICE. At present, a pre-compiled installation of VICE is not available through conda, though users who typically install their python packages and manage their computing environments with conda can safely conduct their installation of VICE using pip. As noted below, VICE has no run-time dependencies, meaning that there is no environment that would need solved in the event the installation were conducted using conda. In this case, the package manager would simply see that the list of dependencies is empty, then download the pre-compiled binary and install it.

If you have already installed VICE and would like help getting started, we recommend checking out VICE’s tutorial. Further usage guidelines can be found here.

Contents

• Installing VICE

  • Dependencies

    • A Note on Implementation

  • Manual Installation

    • Additional Compile Options

    • Things to Avoid

  • Troubleshooting Your Build

    • Running the setup.py File Failed

    • Running the Tests Resulted in a Segmentation Fault

    • VICE Isn’t Running from the Command Line

    • Compiler Failure

  • Uninstalling VICE

Dependencies

VICE has no primary run-time dependencies; that is, it does not require any external software to run properly. All that is required to run VICE is python itself. There are however a handful of features which are enabled when certain dependencies are satisfied, and we recommend users install them to make use of VICE to its full extent. These secondary dependencies are as follows:

1. dill >= 0.2.0

   dill allows VICE to save python functions with its output. This makes it possible to reconstruct simulations from their output.

2. matplotlib >= 2.0.0

   matplotlib is necessary for the show function of the output object. This is intended to allow users to visually inspect the results of their simulations in ipython, a jupyter notebook, or something similar without having to plot it themselves. This is included purely for convenience, and is not intended to produce publication-quality figures.

3. NumPy

   VICE’s tutorial and example code often make use of NumPy, but the user does not need NumPy to use VICE.

A Note on Implementation

VICE is implemented in ANSI/ISO C and is wrapped using only standard library Python and Cython. It is thus independent of the user’s version of Anaconda (or lackthereof). It is NumPy- and pandas-compatible, but neither NumPy- nor pandas-dependent. That is, it will recognize user input from both NumPy and pandas data types such as the NumPy array or the pandas dataframe, but is designed to run independently of them.

Manual Installation

Users who have modified VICE’s source code must compile and install their updated version manually. Otherwise, we recommend simply making use of pip as described above. If you have already modified VICE’s source code or plan to do so, we encourage you to reach out to one of our developers - we’d be happy to consult with you to help VICE meet your needs!

While VICE does not have any primary run-time dependencies, there are a few common compile-time dependencies that must be satisfied to install from source. They are as follows:

1. Python >= 3.6

2. setuptools >= 18.0

3. Make >= 3.81

4. gcc >= 4.6 or clang >= 3.6.0

On Mac OS X and Linux architectures, it is likely that Make and one of gcc or clang come pre-installed. Users may install with alternative C compilers if they so choose, but VICE is tested with only gcc and clang. While a sizable portion of VICE’s source code is written in Cython and requires Cython >= 0.29.0 to compile, this should be handled automatically by setuptools. Nonetheless, it is always an easy option to install it manually via python -m pip install Cython>=0.29.0.

Once the build dependencies are satisfied, download the source code using a terminal and change directories into the source tree:

$ git clone https://github.com/giganano/VICE.git
$ cd VICE

From here, users may change to a specific branch if necessary. For example, VICE’s latest development version is on a branch named development, and git checkout development will take you there. To then compile and install VICE, simply run:

$ make
$ python setup.py build install [--user]

This will compile the source code under a directory named build, and subsequently install to the appropriate site-packages directory once completed. Users who do not have administrator’s privileges on the system they’re conducting the installation should add the --user command-line argument, which will conduct a local installation.

Following the installation, running VICE’s unit tests (if desired) and cleaning the source tree can be achieved with

$ make tests
$ make clean

Please note that users installing VICE to multiple versions of python will likely have to run make clean between runs of the setup.py file. The command make tests runs the unit tests in the current environment’s default version of python. If a specific version of python is required, the tests can be ran from within the interpreter itself easily:

import vice
vice.test()

If you have issues installing or running VICE, please see the section on Troubleshooting Your Build. If your installation was successful and you would like help getting started, usage guidelines can be found here.

Additional Compile Options

VICE affords users flexibility in specifying how they’d like to compile from source.

1. Parallelization

   Users may spread out the job of compiling VICE across multiple cores via the [-j N] command-line argument. For example,

   $ python setup.py build -j 2 install [--user]
   

   will compile all extensions using 2 cores. Warning: See note below regarding parallel installations with the gcc C compiler.

2. Suppress verbose output

   Users may suppress the printing of compiler commands to the consoler with the [-q --quiet] command-line argument. For example, when running

   $ python setup.py build --quiet install [--user]
   

   the only lines printed to the console by the setup.py file will say that specific extensions are being cythonized.

3. Individual extensions

   If VICE’s source code has already been compiled and is located in the build directory, then the entire code base does not need to be re-compiled every time a small modification is made. The name of the extension, which can be determined via the relative path to the file, is all that is required. For example, the vice.singlezone object is linked to VICE’s C library in the file vice/core/singlezone/_singlezone.pyx, so the name of its extension is vice.core.singlezone._singlezone. To recompile this extension only and reinstall with all previously compiled extensions, simply run

   $ python setup.py build ext=vice.core.singlezone._singlezone install [--user]
   

Things to Avoid

1. Parallelization with the gcc compiler

   Users manually installing VICE with the gcc C compiler should omit the [-j N] command-line argument from their call to VICE’s setup.py file (see Additional Compile Options above). In practice, the developer’s find that gcc is not able to successfully complete compiling VICE across multiple cores. This should be a non-issue for those running Mac OS, as gcc must be installed and clang is the default compiler. For those on Linux, however, gcc is the default.

2. Simultaneous installations

   Users manually installing VICE from source for multiple versions of python should not run the setup.py file in separate terminals simultaneously; this will cause one of the builds to fail. Likewise, users should not run the tests for multiple versions of python simultaneously; this will almost certainly cause a segmentation fault.

Troubleshooting Your Build

The following are a number of issues that can arise when manually installing VICE. If none of these options solve your problem, or if you attempted an installation with pip as opposed to installing manually, please open an issue here.

Running the setup.py File Failed

Did you run it for multiple versions of python simultaneously? Alternatively, did you run a parallelized installation using the gcc C compiler? If neither is the case, please open an issue here.

Running the Tests Resulted in a Segmentation Fault

Did you run the tests for multiple versions of python simultaneously? If not, please open an issue here.

VICE Isn’t Running from the Command Line

If vice doesn’t run from the terminal after installing, first check that python3 -m vice runs; the two have the same functionality. If neither work, then it’s likely there was an issue with the installation, and we recommend rerunning the install process, making sure that the instructions are followed as closely as possible. If this still does not work, please open an issue here.

If python3 -m vice works, but vice does not, then it’s likely that that command line entry was copied to a directory not on your PATH. The simplest patch for this issue is to create an alias for vice mapping it to the longer command. This can be done by adding the following line to your ~/.bash_profile:

alias vice="python3 -m vice"

Then either run source ~/.bash_profile or restart your terminal for the alias to take effect.

Alternatively, the proper file can simply be copied to any given directory in your computer. If this directory is not on your PATH, then your PATH must be modified to contain this file’s new location. For example:

$ cp ./bin/vice ~/.local/bin

This will place the command line entry in the ~/.local/bin/ directory, which can be permanently added to your path by adding

export PATH=$HOME/.local/bin:$PATH

to your ~/.bash_profile. As with the alias solution, this will require either running source ~/.bash_profile or restarting your terminal to take effect.

Note: If you have installed VICE with the --user option, it is likely that VICE has automatically made the above modification to your PATH, and that either running source ~/.bash_profile or restarting your terminal is all that is required after copying the file to ~/.local/bin. If you have copied the file to a different directory, VICE will not have added that file to your PATH.

More information on modifying your PATH can be found here.

If this does not fix the issue, please open an issue here.

An alternative workaround to this issue is to create an alias for vice by adding the following line to

Compiler Failure

This is usually an indication that the build should not be ran on multiple cores, which is usually the case with the gcc C compiler. First run make clean, and subsequently make. Then replace your previous command to run the setup.py file with:

$ python setup.py build install [--user] [--quiet]

If you were not installing VICE on multiple cores to begin with, try installing without the build directive:

$ python setup.py install [--user] [--quiet]

If neither of these recommendations fix your problem, please open an issue here.

Uninstalling VICE

If you have installed VICE from PyPI, it can be uninstalled from the terminal via pip uninstall vice. When prompted, simply confirm that you would like the files removed. If you have downloaded VICE’s supplementary data for use with the milkyway object, it is recommended that you remove these files first by running

import vice
vice.toolkit.hydrodisk.data._h277_remove()

before the pip uninstall vice command.

If you have installed from source, uninstalling requires a couple of steps. First, you must find the path to the directory that it was installed to. This can be done by launching python and running the following two lines:

import vice
print(vice.__path__)

Note that there are four underscores in total: two each before and after path. This will print a single-element list containing a string denoting the name of the directory holding VICE’s compiled extensions, of the format /path/to/install/dir/vice. Change into this directory, and remove the VICE tree:

$ cd /path/to/install/dir/
$ rm -rf vice/

Then, check the remaining contents for an egg. This will likely be of the format vice-<version number>.egg-info. Remove this directory as well:

$ rm -rf vice-<version number>.egg-info

Finally, the command line entry must be removed. The full path to this script can be found with the which command in the terminal:

$ which vice

This will print the full path in the format /path/to/cmdline/entry/vice. Pass it to the rm command as well:

$ rm -f /path/to/cmdline/entry/vice

If this process completed without any errors, then VICE was successfully uninstalled. To double-check, rerunning which vice should now print nothing, and attempting to import VICE into python should result in a ModuleNotFoundError.