Ubuntu walkthrough

Ubuntu walkthrough#

In this section, we provide a demonstration of how to get EPOC++ up and running in a newly installed Ubuntu 22.04.3 system.

Obtaining the code from Git#

Firstly, the computer must be set up to run git. If you do not have git installed, this can be done by opening a terminal and running:

$ sudo apt install git

Once git is installed, the code can be copied from Warwick’s private repository, provided you have been given access. If this is your first time using git on this machine, you will need to perform a few tasks to validate your permission first. You’ll need to create a GPG key, install a credential manager, and link the GPG key to your local git environment and your Github account. I provide notes detailing how I went about this:

  • Generate a key using GPG (pre-installed in 22.04.3), by running from the terminal:

$ gpg --full-generate-key

  • Enter 1 when prompted for the key-type (for an RSA key).

  • Hit enter when prompted for keysize, choose a length of validity for the key, enter user ID information. Select and confirm a password for the key.

  • Some lines will be printed when the key is created. The long line of numbers and letters between the lines starting pub and uid is your key-id. Save this - you will need it multiple times!

  • To view your full public key, run:

$ gpg --armor --export key-id

where you replace key-id with the copied key-id. Copy everything printed by this command.

  • Open a web-browser, navigate to github.com and sign in.

  • Click your profile image in the top-right corner, and enter settings, then SSH and GPG keys. Click the green New GPG key button.

  • Enter a title to describe the machine the key is for, and paste the PGP public key block into the key box.

  • Press the Add GPG key button.

You now have a GPG key, and have linked it to Github. Next, you need to associate it with your local git environment. Install the git-credential-manager by following the instructions at this URL: git-ecosystem/git-credential-manager

  • For Linux, download the tarball. I downloaded the file: gcm-linux_amd64.2.4.1.tar.gz on git-ecosystem/git-credential-manager

  • For Linux, unpack the tarball. I used the terminal command:

$ sudo tar -xvf ~/Downloads/gcm-linux_amd64.2.4.1.tar.gz -C /usr/local/bin

  • To set up the credential store on Linux, use:

$ git-credential-manager configure
$ git config --global credential.credentialStore gpg

  • Next, link the credential manager to the previously generated GPG key.

 $ sudo apt install pass
 $ pass init key-id

where again, you replace key-id with your saved GPG key-id.

At this stage, your machine should now be linked to the GitHub account with access to the private repositories in Warwick-Plasma. Download the code using:

$ git clone https://github.com/Warwick-Plasma/EPOCpp.git

You will be prompted to continue in a browser, continue and follow the prompts until the code is downloaded.

Building the code#

To compile the code, we must ensure that compiler packages have been installed. Both cmake and g++ must be installed in your system, which can be done using

$ sudo apt install cmake g++

Once you have the compilers set-up, you can build the code by running the following lines from a terminal:

$ cmake -Bbuild .
$ cmake --build build

Running the code#

The most basic way to run an EPOC++ simulation is to run from an input.deck file. A collection of example input decks is provided in EPOCpp/example_decks

Once a file called input.deck has been created (one already exists in the example deck directory), the user can run the code by navigating to the directory containing the executable. If following this demo, this will be in EPOCpp/build/bin. Once here, run:

$ ./epocpp

and when prompted, enter the full path to the directory containing the input.deck. If an output block is specified in the input.deck, then output files will be written to the same input.deck directory. These will be of the form: dataXXXXX.epc.

Reading the output#

Two files have been provided for reading dataXXXXX.epc files, one in Python and one in MATLAB:

  • Python: EPOCpp/epc_readers/epc_parser.py

  • MATLAB: EPOCpp/epc_readers/read_epc.m

If following this guide, python3 will already be installed on your device. To do Python data analysis, navigate to the epc_readers directory in a terminal, and launch an interactive session:

$ python3

When in Python, you can run the following code to extract the data from an epc file:

from epc_parser import epc
data = epc('/path/to/data00010.epc')

To access data from the epc class variable data, you can run something like:

Ex = data.get_array('/data/meshes/E/x')

and a list of available variable names can be obtained by running

data.get_array_names()

Alternatively, if the user has MATLAB, then they may copy the function read_epc.m to the working directory (or add it to the path), and extract data using

data = read_epc('data00010.epc');

which writes the variables to a MATLAB structure.