Installing ASSET

In most cases we suggest simply installing ASSET via pip, which is as simple as running the following command in the console:

pip install asset-asrl

We currently host Windows and Linux binaries for python 3.7-3.12 on PyPi.

If you are interested in building ASSET from source, please see the following sections for a step-by-step guide on how to do so on:

  • Windows

  • Linux

  • Docker (Linux)

Build from Source on Windows

In order to build ASSET on Windows the following dependencies are required:

Step-By-Step Guide

  1. We will begin by installing Visual Studio (VS).

    Follow the VS installation prompts until you are prompted to select any additional packages to install with VS. Here we will want to select Desktop development with C++; however, we are going to make one change to the defaults for the C++ install and un-check the option for “C++ Clang tools for Windows” (shown below).

    ../_images/vsstudiodesktopc%2B%2B.png

    Also ensure that the “C++ CMake Tools for Windows” is checked. After doing this continue and finish the installation.

    ../_images/VSoptions.PNG

  2. Next we will install the LLVM Compiler Toolkit. An LLVM installation of at least LLVM-11 is required, and we recommend using the latest version if possible.

    Navigate to the LLVM github releases page, select your desired version, and download the LLVM win64 installer (LLVM-15.0.0-win64.exe for example). Proceed with the LLVM install, however ensure that the install option “Do not add LLVM to the system PATH” is checked. After finishing the LLVM installation we can proceed with installing Intel MKL.

    ../_images/LLVMnopath.PNG

  3. Download and install the Intel oneAPI MKL, using the offline installer.

    Install with the recommended settings and then proceed to installing Anaconda, if desired. If you are not using Anaconda you may skip the next step.

  4. Now download and install Anaconda.

    Check that Anaconda is set to be placed on the PATH and set Anaconda to be your default Python. Additionally install the following packages.

    • SpiceyPy, Sphinx, and Furo

    Your version of Anaconda may be installed in “ProgramData” and may be named “Anaconda”, “Anaconda3”, or “anaconda3”, depending on your installation settings.

    ../_images/anacondainstall.PNG

    After installing anaconda, it may be necessary to upgrade numpy through pip, due to potential compatibibility issues with numpy’s version of libiomp5md.dll and Intel MKL’s version.

    pip install numpy --upgrade

    Warning

    if you aren’t using anaconda, you are still going to need numpy (comes with anaconda by default).

  5. Next we will be adding the required system and PATH variables to build ASSET.

    First, add the Intel oneAPI to a new system variable named “ONEAPI_ROOT” and set the variable value to your oneAPI install directory, as shown below. If your install directory is different, be sure to point this to the correct folder. This may have already been set when you installed oneAPI.

    ../_images/oneapiroot.PNG

    Warning

    If you are using an Alder Lake or Raptor Lake Intel CPU it may be beneficial to add the system variable “MKL_ENABLE_INSTRUCTIONS” with value “AVX” as well.

  6. We also need to add a few variables to our Path.

    The following directories should be added to your system PATH and set as your default Python install. Once again, be sure to point this to the actual location of the relevant folders on your computer.

    ../_images/anacondapath.PNG

  7. Now, clone the ASSET repo to where you want it to live.

    If you are cloning from the command line, make sure to call git submodule update --init --recursive inside of the repository after cloning to ensure that the dependencies are downloaded.

  8. We are almost there! Now, open VS and be sure to run it as administrator to avoid any conflicts when building the Python library. Additionally, ensure that your Python IDE is closed during this step.

    Open the ASSET folder with VS and wait for it to finish loading. After VS has finished loading the ASSET repo directory, navigate to the CMakeSettings.json file. Here it is recommended to change the integer number of threads to be the amount of RAM your computer has divided by 3 (rounded down).

    ../_images/cmakejson.PNG ../_images/threads.PNG

    Now we are going to configure the ASSET CMake settings by going to the project dropdown menu and selecting “Configure ASSET” or “Configure Cache” (depending on the version of VS). Wait until the output message from CMake says that it is finished and proceed to the build step.

    ../_images/config.png

    The last step is to actually build ASSET! After the configuration step has completed navigate to the Build dropdown menu and choose “Build All” (or Ctrl + Shift + B). Keep your Python IDE closed until the build completes.

    ../_images/build.png

  9. With that you should have a successfully built ASSET Python library and are ready to get started with the rest of the tutorials.

    To import ASSET simply use the following in your Python IDE

    import asset_asrl

Build from Source on Linux

The dependencies for Linux installations are similar to that of Windows; however, we’ll be using Visual Studio Code for our IDE:

Step-by-Step Guide

This guide was written assuming that the user has a working Ubuntu installation; however, ASSET will work with other Linux distributions. Simply use the appropriate commands to install the required packages. If it is desired to use an IDE other than Visual Studio Code, it is still required that a version of CMake of at least 3.16 is installed.

  1. We will begin by installing Visual Studio Code (VSCode).

    Install VSC as desired, along with the C/C++ and CMake Tools Extensions.

  2. Now, install LLVM clang using the package manager.

    sudo apt install clang lldb lld

    • or if you desire to use gcc

      sudo apt update
sudo apt install build-essential
gcc --version

  3. Download and install the Intel oneAPI MKL, using the offline installer. The complete Linux installation guide for Intel oneAPI can be found here.

    Note

    We recommend that you use the oneAPI gui installer through the Intel website; however, if it necessary to install via the bash terminal, those directions can be found here.

    Install with the recommended settings and then proceed to installing Anaconda, if desired. If you are not using Anaconda you may skip the next step.

  4. Now, download and install Anaconda.

    • Use pip to install SpiceyPy.

      if you are using anaconda rather than a generic python installation, it may be necessary to upgrade numpy through pip, due to potential compatibibility issues with numpy’s version of openmp and Intel MKL’s version.

      conda install nomkl

      Even if you already have anaconda or a python distribution installed you will need these packages.

      • SpiceyPy, Sphinx, and Furo

      Warning

      if you aren’t using anaconda, you are still going to need numpy (comes with anaconda by default).

  5. Next, we will set the required system variables to build ASSET.

    Use the source command to properly setup the oneAPI variables.

    source /opt/intel/oneapi/setvars.sh

  6. Now, clone the ASSET repo to where you want it to live.

    Note

    If you are cloning from the command line, make sure to call git submodule update --init --recursive inside of the repository after cloning to ensure that the dependencies are downloaded.

  7. After installing the dependencies, open VSCode to build ASSET.

    Configure the VSCode CMake extension to use the Ninja generator. You may need to install Ninja.

    apt install ninja-build

    Select the type of build (1) you wish to perform (Release is correct if you are going to be running code using ASSET), and kit to use (2) (gcc or clang).

    ../_images/vscodevariant.PNG

    Now hit build to begin building ASSET

    ../_images/vscodebuild.png

  8. With that you should have a successfully built ASSET Python library and are ready to get started with the rest of the tutorials.

    To import ASSET simply use the following in your Python IDE

    import asset_asrl

Docker

The dockerfiles folder in the repo contains docker files and supporting scripts for building asset_asrl .whl files for pip installation on linux systems. Two images are provided based on Ubuntu 18.04 and 20.04. Build wheels on 18.04 for better compatibility with older linux distros or 20.04 for better performance.

To use, cd to the desired image’s folder and build the image. You may optionally set the number of cores used building the image with the CMakeBuildJobs build argument.

cd Ubuntu18.04

docker build -t assetbuild . --build-arg CMakeBuildJobs=12

After building the image, start up a new container.

docker run -it assetbuild /bin/bash

Once inside the container, run the BuildWheel.sh script to build a .whl file for a particular python version (-p), repo branch (-b). You may also set the number of jobs used when compiling with the -j argument.

bash ~/BuildWheel.sh -b master -j 12 -p 3.10

After the build has completed, the packaged wheel file will be available in ~/asset_asrl/wheelhouse. You can then copy this file out of the container for installation on other systems.

Next Steps

If this is your first time using ASSET, it’s now recommended that you begin reviewing the remaining tutorials, such as Vector Function Tutorial. After you feel comfortable with some of ASSET’s coding paradigms, a select set of tutorials that highlight ASSET’s features and capabilities are provided in Examples.