Installation¶
1. Download PUNC++¶
Make sure you have Git installed, and clone PUNC++ from GitHub as follows:
cd ~ # or the location of your choice
git clone https://github.com/puncproject/PUNCpp.git punc++
cd punc++
2a. Using the PUNC++ Anaconda environment (recommended)¶
We maintain an Anaconda environment which provides all dependencies of PUNC++, as well as other packages facilitating our workflow. To create the PUNC++ environment, make sure you have Conda 4.7.5 or newer (conda can be updated through conda update -n root conda). Then create the environment as follows:
$ cd envs
$ conda env create -f punc.yml
Whenever you wish to work with PUNC++, you activate the environment as follows:
$ conda activate punc
In addition, we recommend that you install the following tools outside of Anaconda:
They do not come bundled with the Anaconda environment due to conflicts with other packages in the environment.
2b. Installing dependencies manually¶
If you do not want to use the above-mentioned Anaconda-environment, you may install the following dependencies manually:
In addition, FEniCS must be compiled with at least the following optional dependencies:
Since updates to FEniCS (and its dependencies) frequently breaks backwards compatibility, we recommend using the version listed on this page. This is the one we have most recently tested and used. Several installation methods are described on the FEniCS website. We point out that depending on how FEniCS and its dependencies are installed, there may be a tenfold difference in the performance of PUNC++, since not all installations have the same level of optimization.
In addition we recommend installing the following tools for pre- and post-processing:
3. Installing PUNC++¶
PUNC++ comes in two parts: a library (in the folder punc++/punc) and an executable program (in punc++/interaction). The library contains every computational aspects in a modular fashion, and allows the developer to re-use bits and pieces in different ways and to perform custom tests and benchmarks on individual parts of the library. The executable makes use of the library to perform plasma-object interaction simulations. To build the library:
cd punc
./build.sh
The library will be installed in a local folder punc++/punc/install. It can also be installed in system-wide folders by running ./install.sh instead of ./build.sh, but we recommend just using ./build.sh.
Developer’s documentation of the library can be generated by running:
./doc.sh
The documentation is then available in the file doc.html.
To install interaction:
cd ../interaction
./build.sh
4. Testing PUNC++¶
To test that the installation is successful, you may run an integration test that runs interaction and the underlying PUNC++ library as follows:
cd ../test
./test.sh
It should run for a few minutes and then say TEST PASSED (relative error < 3%). Note that the relative error is statistical in nature, and PUNC++ do not yet have a mechanism to lock the seed of the random number generator. The test may therefore on rare occasions fail with an error slightly higher than 3%. If that happens, run the test again. An actual error will usually be evident, having a much, much larger error, or not reaching this point in the test at all.
5. Introduction to FEniCS (for developers)¶
For developers it may be of interest to make themselves familiar with FEniCS. The FEniCS tutorial is of relevance, especially the section called “Fundamentals: Solving the Poisson equation”.