feeLLGood – Tools

The tools directory contains a few useful Python scripts and the C++ source code of the tool rev_CMK:

fg-merge-sol: combine a mesh file with a matching .sol file

This script combines a mesh file (which has the node coordinates) with a magnetization configuration in feeLLGood’s ‘.sol’ format (which has the node reduced magnetizations). It outputs the reduced magnetization as a function of position, in a tab-separated-values file with six columns: (x, y, z, m_x, m_y, m_z). Example:

fg-merge-sol mymesh.msh mysol.sol -o output_file

The comments and metadata of the ‘.sol’ file are also copied to the output file. If the -o option is not provided, the output is sent to stdout.

convert2vtk: convert FeeLLGood's output .sol files to paraview format

This script uses gmsh and the VTK framework, the 3D engine inside paraview. To install them, type in a terminal:

pip3 install --upgrade --user vtk gmsh

convert2vtk is a command line tool to convert a feellgood output .sol file into a .vtu file. You have to provide the mesh file to create the .vtu file. Example:

convert2vtk mymesh.msh mysol.sol

convert2vtk does not affect the .msh and the .sol files, it creates a new .vtu file. Technically, the .vtu file is a XML file, with data written in binary. It uses a VTK unstructured grid for both the mesh and the associated magnetization values. If only mesh file name and .sol file name are provided to convert2vtk , then it is using columns 1, 2 and 3 of the .sol file as magnetization components. If the user wants to write others quantities to .vtu output file, he has to give the indices of the columns within the .sol file. Example:

convert2vtk mymesh.msh mysol.sol 3 4

With thoses indices, the output file will contain the corresponding columns, and they will be encoded as VTK scalars in the .vtu file. The index column convention is starting from zero.

The .vtu file name is built from the .sol file name, replacing its extension.

convert2hdf5: convert FeeLLGood's output .sol file(s) to hdf5 format

This script uses h5py framework to create a hdf5 file storing all the results of a feeLLGood simulation. It stores both the input yaml script that was provided to FeeLLGood, the .evol file and the .sol file(s) within the same hdf5 file, and various metadatas. The structure is the following:

HDF5 root
    ├── group:<group_name>                     one group per simulation
    │   ├── attribute:settings                 YAML file
    │   ├── attribute:mesh                     mesh file in MSH 2.2 format
    │   ├── attribute:"feeLLGood version"
    │   ├── attribute:hostname
    │   ├── attribute:"real-world time"        when the simulation was started
    │   ├── dataset:evolFile                   evolution of global quantities
    │   │   └── attribute:columns              column names
    │   ├── dataset:solFile<iteration_number>  one snapshot
    │   │   └── attribute:time                 time in the simulation
    │   ├── dataset:solFile<iteration_number>  another snapshot
    │   ⋮
    └── group:<group_name>                     another simulation

To install h5py for Python, type in a terminal:

pip3 install h5py

convert2hdf5 is a command line tool that needs two or more arguments. First is the file name that will be generated, second is the settings file name, and optionally the user may provide some .sol files. If no .sol file is provided, convert2hdf5 will uses all .sol files in the current directory. Example:

convert2hdf5 mySim.h5 settings.yml

This above example will generate a mySim.h5 file, with the following internal hierarchy: a group 'results' is at the root of the file, with attribute 'settings'. It is a string that is a copy of the settings.yml file. Within the group 'results', various datasets are found :

• a dataset named evolFile contains the data of the .evol file found in the working directory, with an attribute 'metadata' to store the .evol metadata's.
• some datasets named solFile*. Each of them corresponds to a .sol file. They contain the magnetizations and the potential for each nodes, with some attributes:

We recommend the reading of the h5py quick start guide to become familiar with hdf5 outputs of convert2hdf5 tool, and to be able to manipulate them. A browser such as hdfview, or silx might help. From command line, the tool h5dump is also very convenient.

If the user wants to add his simulation results to an existing hdf5 file in a new group, option '-a' or '–append' with a group name can be passed. Example:

convert2hdf5 -a latestResults mySim.h5 settings.yml

If that group name already exists, convert2hdf5 exits, otherwise it is creating the group and stores settings, .evol and .sol files as mentionned above. If the hdf5 file does not exists, then it is created with the given group name instead of using 'results'.

h5extract: extract from a hdf5 file FeeLLGood's output .sol file(s), .evol file , yaml settings

This script uses h5py framework to extract from a hdf5 file previously created by convert2hdf5 the text files .sol, .evol, .yml of a feeLLGood simulation. It is also a convenient tool to see what is in a hdf5 file, for example:

h5extract simuls.h5 --view

will print to the terminal all the groups (name) and their attributes (name and content), and the datasets (name). A prefix 'a' for attribute and 'd' for dataset to ease the reading of the hdf5 file content. If the user only wants to see the contents of a single group named 'myGroup', he should use the option '-g':

h5extract simuls.h5 --view -g myGroup

To extract all the data of a group from the hdf5 file, the user should type:

h5extract simuls.h5 -g myGroup -b myBasename

This command will create a file .evol; a .msh file, a .yml settings file and all the .sol files computed with the corresponding settings, including the last .sol if the simulation was interupted before its termination. The associated metadata stored in various attributes are rebuilt as text headers in the relevant text file. Each created file will start with myBasename prefix. The user should be aware that extracting all the content of a hdf5 file might create a lot of files, occupying an important amount of disk space. If the user only wishes to recover a part of the data stored in a hdf5 file, the option '-w' should be used. There are five different ways of using '-w' option:

Example of the extraction of the settings:

h5extract simuls.h5 -g myGroup -b vortex -w settings

This will create a text file vortex.yml of the settings stored in the group myGroup in the hdf5 file simuls.h5.

Example the extraction of a single .sol dataset:

h5extract simuls.h5 -g myGroup -b vortex -w sim_iter150

This will create a .sol text file vortexsim_iter150.sol of the existing dataset sim_iter150 stored in the group myGroup in the hdf5 file simuls.h5.

rev_CMK: apply reverse Cuthill-McKee algorithm to a mesh file

The C++ source code of rev_CMK is in the sub-directory /tools/rev_CMK. This program depends on the Boost library, which can be installed as follows:

# On Ubuntu and Debian:
sudo apt-get install libboost-dev

 # On Rocky Linux:
sudo dnf install boost-devel

To build the executable, once the Boost library is installed on your workstation, type:

cmake .
make

You may install the binary typing:

sudo make install

The input file mesh must be a text file, compatible with gmsh format 2.2. Example:

rev_CMK my_raw_mesh.msh

The tool rev_CMK will apply to the input mesh the reverse Cuthill-McKee algorithm, and create a new mesh file with the new indices, with extra extension .r_cmk. It also tells you the bandwidth reduction. If some extra metadata is stored in the input mesh file, it is copied to the re-indexed mesh file. On a Linux distribution, if the mesh file was generated from a Windows computer, you may have to use the dos2unix command line tool before running rev_CMK.