Manual Installation

Getting Components

General Information

The Git version control system is fundamental to the evolution, storage, and retrieval of turboWAVE components.

TurboWAVE components are maintained in a single repository. Unless you are doing development yourself, you will typically interact only with the master branch. The commits that make up the master branch have varying degrees of stability. Stable releases are identified by a tag. The tag may have letter suffixes a, b, or rc, indicating alpha, beta, or release candidate. A numerical tag with no letter suffix is the most stable.

The turboWAVE repository is at https://github.com/USNavalResearchLaboratory/turboWAVE.

Cloning the Repository

The first step to getting the components is to clone the repository. This copies the entire history of the code to your local computer (storage requirement is in the tens of megabytes). Perform the following procedure:

  1. Open a terminal window

  2. Test to see if you have Git installed by executing git --version

  3. Install Git if necessary.

    • Anaconda — conda install git

    • MacOS with Homebrew — brew install git

    • Ubuntu — sudo apt install git

    • Windows — winget install Git.Git (run as administrator)

  4. Navigate to the directory where you want to install turboWAVE (you don’t need to make an enclosing directory).

  5. git clone https://github.com/USNavalResearchLaboratory/turboWAVE.git

Switching to a Stable Version

When you clone the repository the active files (the version you have checked out) will likely be the latest commit, which is not necessarily the most stable. In order to select a stable version perform the following procedure.

  1. Open a terminal and navigate to turboWAVE.

  2. git tag --list

  3. Choose the latest tag without a letter suffix, latest_stable_tag.

  4. git switch --detach latest_stable_tag.

    • To go back from the detached state use git switch master, or, to automatically throw out any changes, add the -f flag.

Note

if you are viewing this documentation on readthedocs, you are likely viewing the latest documentation which is not necessarily the stable documentation. There should be a hovering dropdown to select between the two.

Tools Installation

General Notes

Most of the tools are built on Python 3. It is highly recommended to operate in a virtual environment. Virtual environments can be created using native Python tools, or Anaconda.

Tools are synchronized with core to within major and minor version numbers (the patch and build numbers may differ). For the best results, keep the installed versions consistent.

Python Module twutils

  1. You can create a conda environment with the necessary modules and scripts using conda create -n NAME -c dfxgordon twutils, where NAME is the name of the environment (your choice).

  2. You can install from the local repository using pip install . (note dot) from within the turboWAVE/tools/twutils directory.

Python DataViewer (optional)

  1. The Python DataViewer has to be run in a Jupyter Notebook.

  2. Copy turboWAVE/tools/DataViewer.ipynb to wherever you keep your notebooks

  3. Create a directory ~/.jupyter/custom/ and copy turboWAVE/tools/config-files/custom.css to the new directory.

Input File Support (optional)

You can add language support for turboWAVE input files in various editors.

  1. For VS Code, language support can be installed using the editor’s own GUI, search for turbowave.

  2. To enable turboWAVE input file syntax highlights with the micro editor

    • Copy turboWAVE/tools/config-files/turbowave.micro.yaml to %HomePath%\.config\micro\syntax\ (Windows) or ~/.config/micro/syntax/ (others).

  3. To enable turboWAVE input file syntax highlights with the nano editor

    • Copy turboWAVE/tools/config-files/.turbowave.nano to your home directory.

    • Edit (create if necessary) %HomePath%\nano.rc (windows) or ~/.nanorc (others) and add the line include "~/.turbowave.nanorc".

  4. To enable turboWAVE input file syntax highlights with the vim editor

    • Copy turboWAVE/tools/config-files/filetype.vim to %HomePath%\vimfiles\ (Windows) or ~/.vim/ (others)

    • Copy turboWAVE/tools/config-files/turbowave.vim to %HomePath%\vimfiles\syntax\ or ~/.vim/syntax/ (others).

Core Installation

As of this writing there is only one build system that can be used, CMake. This is because only CMake fully supports C++20 modules.

Configuration

  1. Manually edit base/config.h.in

Performance Tuning Parameters

There are a few parameters hard coded in source that can be used to tune performance. These are as follows.

  1. Particle bundle size - In base.h, you should change max_bundle_size to be a multiple of vbits divided by 32. The optimal choice is difficult to predict, but a rule of thumb is to make it close to the typical number of particles per cell.

  2. There are some constants in Pusher.cpp, in the method Species::Push, that it may be advantageous to adjust. Namely, the constants min_particles_per_task and preferred_tasks. This has to do with how particles are partitioned among OpenMP threads.

Build and Install

  1. See the comments in CMakeLists.txt

Core Install for HPC

As of this writing we have not found an HPC center with sufficiently up-to-date build tools