feeLLGood – Tools

The tools directory contains a few useful Python scripts:

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.

fg-sol2vtk: 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

fg-sol2vtk 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:

fg-sol2vtk mymesh.msh mysol.sol

fg-sol2vtk 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 fg-sol2vtk , 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:

fg-sol2vtk 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.

fg-sol2hdf5: 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

fg-sol2hdf5 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, fg-sol2hdf5 will uses all .sol files in the current directory. Example:

fg-sol2hdf5 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 fg-sol2hdf5 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:

fg-sol2hdf5 -a latestResults mySim.h5 settings.yml

If that group name already exists, fg-sol2hdf5 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'.

fg-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 fg-sol2hdf5 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:

fg-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':

fg-h5extract simuls.h5 --view -g myGroup

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

fg-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:

fg-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:

fg-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.

fg-gensol: generates initial magnetization configurations (sol.in files)

Overview

fg-gensol is a Python script that generates initial magnetization configurations (sol.in files) for feeLLGood simulations from Gmsh mesh files. It automatically detects physical regions in your mesh and allows you to define custom vector fields for each region. It requires numpy and meshio modules. To install them, type in a terminal:

pip3 install numpy meshio

Step 1: First Run - Generate Configuration

Run the script with your mesh file:

./fg-gensol your_mesh.msh

The mesh file must contain only triangles as surface elements, and tetrahedrons as volume elements, both first order.

Output:

• Creates init_cfg.py with all detected regions
• Lists all regions found in the mesh
• Exits with instructions to edit the configuration

Step 2: Edit Configuration

Open init_cfg.py and customize the vector field for each region:

def define_region_functions():
    """Define vector field for each region (autogenerated)."""
    return {
        'S1': lambda x, y, z: np.array([1, 0, 0]),      # +x direction
        'S2': lambda x, y, z: np.array([0, 1, 0]),      # +y direction
        'S3': lambda x, y, z: np.array([0, 0, 1]),      # +z direction
        'V1': lambda x, y, z: np.array([x/np.sqrt(x**2+y**2), y/np.sqrt(x**2+y**2), 0]),  # vortex
    }

Each function takes coordinates (x, y, z) and returns a 3D vector np.array([mx, my, mz]).

Step 3: Generate Solution File

Run the script again:

./fg-gensol your_mesh.msh

Output:

• Reads your customized init_cfg.py
• Generates sol.in file with magnetization vectors for all mesh nodes

File Structure

your_project/
your_mesh.msh        # Input: Gmsh mesh file (version 4.0+)
init_cfg.py          # Auto-generated configuration (edit this!)
sol.in               # Output: Initial magnetization field

Features

• Automatic region detection: Reads physical groups from Gmsh mesh
• Modular configuration: Configuration separated in init_cfg.py
• Region validation: Warns if regions are missing or undefined
• Auto-regeneration: Updates init_cfg.py if new regions are detected

Common Vector Field Examples

# Uniform field in +x direction
lambda x, y, z: np.array([1, 0, 0])

# Vortex in xy-plane centered at origin
lambda x, y, z: np.array([-y, x, 0])

# Radial field
lambda x, y, z: np.array([x, y, z])

Troubleshooting

Error: "Module 'init_cfg.py' not found"

• Normal on first run - the script will generate it automatically

Error: "Missing regions in init_cfg.py"

• Your mesh has new regions not in init_cfg.py
• The script will regenerate init_cfg.py with all regions

Error: "No physical tags found in mesh.cell_data"

• Your mesh doesn't have physical groups defined
• Define physical groups in Gmsh before exporting

Error: "Unsupported element types"

• Only triangles and tetrahedra are supported
• Reconfigure your mesh to use these element types only

Output Format

The sol.in file contains:

• Header with metadata (hostname, timestamp, version)
• Columns: idx mx my mz phi
  • idx: Node index (0-based)
  • mx, my, mz: Magnetization vector components
  • phi: Scalar potential (set to 0)