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
anduid
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-managerFor 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.