How to use OpenDis Apptainer image

For more information on Apptainer containers and their use, we provide a description of Apptainer, a crash course on how to use Apptainer, and of course there’s also the official Apptainer’s documentation.

Input files

To illustrate the various commands, a set of OpenDis input files is available in the form of an archive via this link. Those files correspond to a tutorial example from the OpenDis official documentation. The archive contains two Python scripts describing the same simulation for OpenDis using two different modules, a sequential one (PyDis) and a multi-threaded one (ExaDis):

• test_frank_read_src_pydis.py,
• test_frank_read_src_exadis.py.

In this tutorial, we will assume that the input files contained in this archive are in the current directory. To extract them:

tar -xzf opendis-tutorial-inputs.tar.gz

Quickstart

For impatient folks, here is how to launch a multi-threaded OpenDis computation on in the case where the current directory contains the opendis.sif container image and all necessary OpenDis input files:

apptainer exec opendis.sif python3 test_frank_read_src_exadis.py

Detailed usage for the OpenDis container

This section presents different ways to use the OpenDis image. For more details about Apptainer commands, please look at this tutorial.

Introduction

OpenDis is a parallelized open-source software designed to simulate and analyze dislocations in crystalline materials at the mesoscale. The code license can be accessed from outside the container as follows:

opendis_path=$(apptainer exec opendis.sif ls /gnu/store | grep opendis)
license_path=$(apptainer exec opendis.sif find /gnu/store/$opendis_path/share -name "LICENSE")
apptainer exec opendis.sif cat $license_path

The current tutorial corresponds to the Frank-Read Source tutorial from OpenDis official documentation. The Python scripts contained in the input archive can also be found in the examples/02_frank_read_src directory of the software GitHub repository.

Simulation description

As described in the tutorial, the initial configuration is a rectangular dislocation loop where all sides are of pure edge type and where all the four corner nodes are pinned. The top arm contains a node that is free to move, which allows it to bow out and act as a Frank-Read source. Periodic boundary conditions are prescribed in all three directions.

Running the simulation with the PyDis module

This first section corresponds to the first part of the tutorial titled Frank-Read Source by Pure Python. The following command runs a simulation with the PyDis module in sequential:

apptainer exec opendis.sif python3 -i test_frank_read_src_pydis.py

If this command is successful, a matplotlib window should with an animation of the simulation should automatically open. The official tutorial shows what this animation should look like.

The -i option in the command above stands for interactive. If this flag is provided, a Python shell will open at the end of the simulation to allow users to interact with the simulation variables. For example, the following command displays all nodes in the dislocation network:

G.all_nodes_tags()

The following command examines the information of a node:

G.nodes((0,0)).view()

The tutorial page presents a few other ways to interact with simulation data from the interactive Python shell.

To exit the shell, simply execute exit() in the shell or use Ctrl+D keys.

Running the simulation with the ExaDis module

This second section corresponds to the second part of the tutorial titled Frank-Read Source by Python calling ExaDiS. It uses the ExaDis module to run the same simulation faster, using the multi-threading OpenMP library. The tutorial specifies that ExaDis should be compiled using OpenMP, which is the case in the current container image.

The following command executes the Frank-Read source simulation with ExaDis:

apptainer exec opendis.sif python3 -i test_frank_read_src_exadis.py

The displayed animation should be the same as previously, and the simulation should be faster. Again, the -i option triggers an interactive Python shell at the end of the simulation. The data stored in object G can be accessed after this manipulation in the interactive shell:

from pydis import DisNet
G1 = net.get_disnet(DisNet)

The new G1 object can then be interacted with exactly as previously.

To go further

OpenDis official documentation contains multiple tutorials presenting the features of the software. The associated Python input scripts can be found in the code repository examples/ directory. The commands presented in this tutorial can be easily extrapolated to run those examples with the OpenDis image container.