1. HiFiMagnet user manual

Welcome to HiFiMagnet manual documentation!

The HiFiMagnet manual documentation introduces the process to install and run an application. New user shall read the HiFiMagnet introduction to have a global view.

HiFiMagnet is a software chain that allows to design and model High Field Magnets. It consists in a set of tools including:

  • MagnetTools

  • HiFiMagnet, multiphics models:

    • Feel++ toolboxes,

    • HiFiMagnet coupled models,

    • Feel++ mqs

2. Quick Starts

2.1. HiFiMagnet plugin matrix

For 3D static analysis:

Native

Docker Container

Singularity Container

Note

hifimagnet

On Debian/Ubuntu Lncmi repository

Recommanded dist: Ubuntu 20.04

On Windows 10 requires MobaXterm for GUI mode

feelpp/feelpp::v0.108

For CG and/or HDG thermo-electric models only

feelpp/hifimagnet:v0.108

hifimagnet-thermobox-P2_9.3.3-v0.108.sif

for singularity 3.2 and later

hifimagnet-thermobox-P2_9.3.3-v0.108.simg

for singularity 2.6
For transient analysis:

Native

Docker Container

Singularity Container

Note

NA

feelpp/hifimagnet:mqs

hifimagnet-mqs.sif

for singularity 3.2 and later

hifimagnet-mqs.simg

for singularity 2.6

2.2. Getting HiFiMagnet

Using HiFiMagnet inside container, either Docker or Singularity based, is the recommended and fastest way. If your system support singularity containers we recommend to use them instead of Docker ones.

2.3. Running HiFiMagnet

2.3.1. from Singularity container

Assuming we use hifimagnet.simg singularity image:

singularity run -it -v $HOME/feel:/feel hifimagnet.simg feelpp_hfm_coupledmodel_3DP1N1 --config-file coupled_3D_P1_N1_singular_cvg.cfg

The coupled_3D_P1_N1_singular_cvg.cfg configuration file holds all the information to specify what calculations are performed. The configuration files are fully described in this section

2.3.2. from Docker container

Start the Docker container feelpp/hifimagnet as follows

docker run -it -v $HOME/feel:/feel feelpp/hifimagnet feelpp_hfm_coupledmodel_3DP1N1 --config-file coupled_3D_P1_N1_singular_cvg.cfg

2.3.3. from command line

To perform a 3D fully coupled multi-physics simulation:

feelpp_hfm_coupledmodel_3DP1N1 --config-file coupled_3D_P1_N1_singular_cvg.cfg

3. Using HiFiMagnet

As stated in introduction HiFiMagnet per se provides tools for High Field Magnets simulation. More precisely we can model:

Table 1. Prepare mesh

docker

singularity

gmsh

gmsh-4.6.0.simg

feelpp_mesh_partitioner

hifimagnet-thermobox-P2_9.3.3-v0.108.simg
Table 2. CG Models (* to be completed *):

Model/Behavior

Executable

Features/Comments

thermo-electric

Magnetostatic

everywhere

only in a zone of interest from a user perspective

Mechanics (CSM)

Fully-Coupled

Lorentz forces computed from an axisymetrical estimation of the magnetic field

3D Lorentz forces

account for thermal dilation

Transient

no CSM, do not account for deformation
Table 3. HDG Models (* to do *):

Model/Behavior

Executable

Features/Comments
Table 4. CRB Models (* to do *:

Model/Behavior

Executable

Features/Comments

The kind of calculation performed is specified in a configuration cfg file. The data settings consist in writting json files for each physical model involved, providing connection between CAD/Mesh entities to respectively Material and Boundary conditions.

In Salome HiFiMagnet plugin section, we have shown how to generate templates for the cfg and json files.

3.1. Mesh for HiFiMagnet

  • generate mesh with Salome HiFiMagnet plugin (see here)

  • convert med to msh format

gmsh -0 -bin HL-31.med -o HL-31.msh

  • eventually partition mesh (mandatory if you plan to run HiFiMagnet in parallel

feelpp_mesh_partitioner --mesh.scale=0.001 --ifile HL-31.msh [--ofile HL-31_p32] --part 32  --nochdir

The number of partition must correspond to the number of jobs that you plan to use for running the app. For instance to run with Singularity :

mpirun -np 32 singularity exec -B $PWD/feel:/feel image.sif feelpp_hfm_coupledmodel_3DP1N1 --config-file ...

On SMB machine (eg. stokes Lncmi server) you can use instead:

singularity exec -B $PWD/feel:/feel image.sif mpirun -np 32 feelpp_hfm_coupledmodel_3DP1N1 --config-file ...

3.2. Data structure

HiFiMagnet simulations parameters are defined througth configuration file .cfg and json files defining the model per physic and eventually some other json files for the physical properties of the materials. Template cfg and json file may be generated with HiFiMagnet Salome plugin (see here).

The data structure follows Feel++ style and convention. In this section we will give details about these different files.

For more infos on cfg and json files see cfg doc. json doc in Feel++ docs.

3.2.1. Config Files

The main configuration file is a cfg file (actually an ini file). It contains all information about the mesh, the models involved etc All information is stored in a [section] except for a few main parameters. An exemple for a full coupled model is given below:

directory=full/HL-31/P1 (1)

case.discretization=P1 (2)

model-file=$cfgdir/M19061901_full.json (3)

compute_magnetism=true (4)
compute_bg_magfield_bmap=true
compute_biotsavart=false
compute_elasticity=true

[gmsh] (5)
filename=$cfgdir/HL-31_withAir_p.json
partition=0

[thermo-electric] (6)
solver=Newton
solver-newton.initial-guess.use-linear-electric=1
verbose_solvertimer=1
error-if-solver-not-converged=1
...

[magnetic_field-bmap] (7)
geo-data=HL-31.d
...

[biot_savart] (8)
box=Box
...

[magnetostatic] (9)
model_json=$cfgdir/M19061901_full.json
...


[elasticity] (10)
filename=$cfgdir/M19061901_full.json
...
1 directory: name of the directory where results will be stored. This path is relative to the default directory defined by FEELPP_REPOSITORY (by default $HOME/feel)
2 case.discretization: keyword to select Finite Element. For CG, use P1 for standard P1 element.
3 model-file: name of the json model file
4 compute options
5 [gmsh] section
6 [thermo-electric] section
7 [magnetic_field-bmap] section
8 [biot_savart] section
9 [magnetostatic] section
10 [elasticity] section
[gmsh] section
[gmsh]
filename=$cfgdir/HL-31_withAir_p.json
partition=0

  • filename: name of the geometry or mesh

  • partition: boolean to instruct code to perform mesh partionning (1) or not (0)

[thermo-electric] section
[thermo-electric]
solver=Newton
solver-newton.initial-guess.use-linear-electric=1
verbose_solvertimer=1
error-if-solver-not-converged=1
ksp-monitor=1
snes-monitor=1
snes-rtol=1.e-10
snes-maxit=100
snes-ksp-rtol=1.e-3
snes-ksp-maxit=4000

# Fieldsplit
pc-type=fieldsplit
fieldsplit-type=additive #additive, multiplicative, symmetric-multiplicative
[thermo-electric.fieldsplit-0]
pc-type=gamg
[thermo-electric.fieldsplit-1]
pc-type=gamg

[thermo-electric.heat]
initial-solution.temperature=290
#verbose=1
verbose_solvertimer=1
pc-type=gamg
ksp-monitor=1

[thermo-electric.electric]
verbose_solvertimer=1
pc-type=gamg
ksp-monitor=1

Solver are specific to each physical model. However in general, the default solver is a direct solver. For large problems, we would prefer iterative solver for efficiency. A typical iterative solver is defined as follow:

  • pc-type: name of the preconditionner,

  • ksp-rtol: relative tolerance to stop iterative solver,

  • ksp-atol: absolute tolerance to stop iterative solver,

  • ksp-maxit: maximum iterations allowed to reach convergence,

  • ksp-use-initial-guess-nonzero: enable to start with a non null initial guess solution.

[magnetostatic] section
[magnetostatic]
model_json=$cfgdir/M19061901_full.json
weakdir=false
#eps-coeff = 1.e-7

[ms]
pc-type=gamg  #boomeramg
pc-view=true
ksp-monitor=1
ksp-rtol=1e-5
ksp-maxit=2000
#ksp-use-initial-guess-nonzero=1
ksp-converged-reason=1
error-if-solver-not-converged=1
[biot_savart] section
[biot_savart]
box=Box
boxdim=3
[magnetic_field-bmap] section
[magnetic_field-bmap]
geo-data=HL-31.d
geo-path=$cfgdir
helix-intensity=0
# helix-auto-intensity=true # mean(I_Helix = (fabs(I0) + fabs(I1))/2.)
bitter-intensity=30000
supra-intensity=0

Section magnetic_field-bmap is specific to HiFiMagnet. It enables to define data needed to compute the "ideal" magnetic field provided by a magnet using B_Map:

  • the .d cfg file describing the Axisymetrical model of the magnet

  • the values for the input currents in each subsets of the magnet

A magnet is composed of PolyHelices insert and eventually some external magnets either Bitter magnets and/or Supraconductor Magnets.
[elasticity] section
[elasticity]
filename=$cfgdir/M19061901_full.json
on.type=elimination_symmetric
lorentz_forces=true
thermal_dilatation=true
# # precondtioner config
pc-view=true
pc-type=gamg #boomeramg #lu,gasm,ml
ksp-maxit=2000
ksp-rtol=1e-5
ksp-monitor=1
ksp-converged-reason=1
error-if-solver-not-converged=1

3.2.2. Physic Model files

The Physic Model files are json files that contain informations about:

  • Materials

  • Boundary Conditions

  • Post-Processing quantities

{
    "Name": "CoupledCart",
    "ShortName":"MSC",
    "Models":
    {
	"use-model-name":1,
	"solid":
	{
	    "equations":"Elasticity"
	},
        "maxwell":
        {
	    "equations":"magnetostatic-cart"
	}
    },
    "Parameters":
    {
	"T0":"293.",

	"U0":"-482.411",
	"Tin":"293.15",
	"h":"85870.2",
	"dTw":"24.23",
	"Tw":"306.746",
	...
    },
    "Materials":
    {
	"H1":
	{
	    "markers":"H1_Cu",
	    "physics":["heat","electric","solid","maxwell"],
	    "alpha":"3.6e-3",
	    "sigma0":"52.4e+6",
	    "k0":"380",
	    "sigma":"sigma0/(1+alpha*(heat_T-T0)):sigma0:alpha:heat_T:T0",
	    "k":"k0*heat_T/((1+alpha*(heat_T-T0))*T0):k0:heat_T:alpha:T0",
	    "E":"117e+9",
	    "nu":"0.33",
	    "alphaT":"18e-6",
	    "rho":"9e+3",
            "mu_mag": "1"
	},
	"H2":
        {
	    ...
        }
	...,
	"R1":
        {
	    "markers":"R1",
	    "physics":["heat","electric","solid","maxwell"],
	},
	...,
	"Isolant1":
	{
	    "markers":"H1_Isolant",
	    "physics":["heat","solid","maxwell"],
	    ...
	},
	...,
        "biotbox":
        {
            "markers":"BiotBox",
	    "physics":["biot"],
            "mu_mag": "1"
        },
        "Air":
        {
            "markers":"Air",
	    "physics":["maxwell"],
            "mu_mag": "1"
        }
    },
    "BoundaryConditions":
    {
	"electric-potential":
	{
            "Dirichlet":
            {
		...
            }
	},
	"temperature":
	{
            "Robin":
            {
		...
            }
	},
        "magnetic_potential":
        {
            "Dirichlet_Biot":
            {
                "A1_InfR1": {}
            },
            "DirichletY":
            {
                ...
            }
        },
	"displacement":
	{
            "Dirichlet":
            {
		...
	    }
	},
        "displacement_z":
        {
            "Dirichlet":
            {
                "R1_BP": { "expr":"0" },
                ...
            }
	}
    },
    "PostProcess":
    {
        "use-model-name":1,
	"maxwell":
	{
	    "Exports":
	    {
		"fields":["magneticPotential","magneticField"]
	    }
	},
        "solid":
	{
            "Exports":
            {
		"fields":["displacement","Von-Mises","tresca","principal-stresses","material-properties"]
	    }
	},
        "thermo-electric":
	{
            "Exports":
            {
		"fields":["heat.temperature","electric.electric-potential","electric.current-density"]
	    }
	},
        "electric":
	{
	    "Save":
	    {
		"Fields":
		{
		    "names":["electric-potential"]
		}
	    },
	    "Measures":
	    {
		"Points":
		{
		    "%1_1%":
		    {
			"coord":"%1_2%",
			"fields":"electric-potential",
			"index1": [ ["V0", "{-21.75e-3,0.e-3,-421.15e-3}"],
                		    ...
				  ]
		    }
		},
		"Statistics":
		{
		    "Intensity0":
		    {
			"type":"integrate",
			"expr":"-electric_iL1_sigma*electric_dnP:electric_iL1_sigma:electric_dnP",
			"markers":"Inner1_LV0"
		    },
		    "Intensity1":
		    {
			"type":"integrate",
			"expr":"-electric_oL2_sigma*electric_dnP:electric_oL2_sigma:electric_dnP",
			"markers":"OuterL2_LV0"
		    },
                    "Power_%1_1%":
                    {
                        "type":"integrate",
                        "expr":"electric_%1_1%_sigma*(electric_dxP^2+electric_dyP^2+electric_dzP^2):electric_%1_1%_sigma:electric_dxP:electric_dyP:electric_dzP",
                        "markers":"%1_2%",
			"index1":[ ["H1", "H1_Cu"],
				   ...
                                 ]
                    }
		}
	    }
	},
	"heat":
	{
	    "Save":
	    {
		"Fields":
		{
		    "names":["temperature"]
		}
	    },
	    "Measures":
	    {
		"Points":
		{
		    "%1_1%":
		    {
			"coord":"%1_2%",
			"fields":"temperature",
			"index1": [ ["T0", "{-3.554e-3,-33.8174e-3,-118e-3}"],
                		    ["T1","{-5.4752e-3,34.5691e-3,135e-3}"]
				  ]
		    }
		},
		"Statistics":
		{
		    "MeanT":
		    {
			"type":["min","max","mean"],
			"field":"temperature"
		    },
		    "MeanT_%1_1%":
		    {
			"type":["min","max","mean"],
			"field":"temperature",
			"markers":["%1_2%","%1_3%","%1_4%"],
			"index1":[ ["Couple1", "H1_Cu", "R1", "H2_Cu" ],
				   ...
				 ]
		    },
		    "MeanT_%1_1%":
		    {
			"type":["min","max","mean"],
			"field":"temperature",
			"markers":"%1_2%",
			"index1":[ ["H1", "H1_Cu"],
				   ...
				 ]
		    },
		    "Flux_%1_1%":
		    {
			"type":"integrate",
			"expr":"%1_2%*(heat_T-(%1_3%+%1_4%/2.)):heat_T:%1_2%:%1_3%:%1_4%",
			"markers":"%1_1%",
			"index1":[ ["Channel0", "h0", "Tin", "dTw0"],
				   ...
				 ]
		    }
		}
	    }
	}
    }
}

3.2.3. Models section

    "Name": "CoupledCart",
    "ShortName":"MSC",
    "Models":
    {
	"use-model-name":1,
	"solid":
	{
	    "equations":"Elasticity"
	},
        "maxwell":
        {
	    "equations":"magnetostatic-cart"
	}
    },

3.2.4. Parameters

    "Parameters":
    {
	"T0":"293.",

	"U0":"-482.411",
	"Tin":"293.15",
	"h":"85870.2",
	"dTw":"24.23",
	"Tw":"306.746",
	...
    },

3.2.5. Materials

Materials may be defined directly in the main json file as in this example:

    "Materials":
    {
	"H1":
	{
	    "markers":"H1_Cu",
	    "physics":["heat","electric","solid","maxwell"],
	    "alpha":"3.6e-3",
	    "sigma0":"52.4e+6",
	    "k0":"380",
	    "sigma":"sigma0/(1+alpha*(heat_T-T0)):sigma0:alpha:heat_T:T0",
	    "k":"k0*heat_T/((1+alpha*(heat_T-T0))*T0):k0:heat_T:alpha:T0",
	    "E":"117e+9",
	    "nu":"0.33",
	    "alphaT":"18e-6",
	    "rho":"9e+3",
            "mu_mag": "1"
	},
	"H2":
        {

Note that for insulator material, you do not need to define all entries. In the following exemple, Isolant1 is only considered in heat model; that is to say that the temperature field will be computed in the domain attached to the markers H1_Isolant.

"Isolant1":
{
  "markers":"H1_Isolant",
  "physics":"heat",
  "sigma":"0",
  "k":"1.2"
}
Materials file

Physical properties of the material may also be defined in a separate json file for each material. The properties are given in SI units.

{
    "name":"Cu", (1)
    "sigma0":"50.e+6",
    "k0":"330",
    "T0":"293",
    "alpha":"3.4e-3", (2)
    "sigma":"sigma0/(1+alpha*(heat_T-T0)):sigma0:alpha:heat_T:T0", (3)
    "k":"k0*heat_T/((1+alpha*(heat_T-T0))*T0):k0:heat_T:alpha:T0", (4)
    "E":"120.e+9", (5)
    "nu":"0.35", (6)
    "alphaT":"18e-6", (7)
    "rho":"8.96e+3", (8)
    "mu":"1" (9)
}

In the table bellow, you will find the correspondance between an entrie in the json file defining properties for material <1> :

Notation

Quantity

Unit

Note

<2> \(\alpha\)

thermal resistivity coefficient

-

<3> \(\sigma\)

electrical conductivity

\(S.m^{-1}\)

an expression of \(T\)

(references values,indiced with a \(_0\), at \(T_0\))

<4> \(k\)

thermal conductivity

\(W.m^{-1} .K^{-1}\)

same

<5> \(Y\)

Young modulus

\(Pa\)

<6> \(\nu\)

Poisson ratio

-

<7> \(\alpha_T\)

thermal expansion coefficient

\(K^{-1}\)

<8> \(\rho\)

material’s density

\(kg.m^{-3}\)

<9> \(\mu\)

magnetic permeability

\(V.s.A^{-1}.m^{-1}\)

3.2.6. BoundaryConditions

    "BoundaryConditions":
    {
	"electric-potential":
	{
            "Dirichlet":
            {
		...
            }
	},
	"temperature":
	{
            "Robin":
            {
		...
            }
	},
        "magnetic_potential":
        {
            "Dirichlet_Biot":
            {
                "A1_InfR1": {}
            },
            "DirichletY":
            {
                ...
            }
        },
	"displacement":
	{
            "Dirichlet":
            {
		...
	    }
	},
        "displacement_z":
        {
            "Dirichlet":
            {
                "R1_BP": { "expr":"0" },
                ...
            }
	}
    },

3.2.7. PostProcess

    "PostProcess":
    {
        "use-model-name":1,
	"maxwell":
	{
	    "Exports":
	    {
		"fields":["magneticPotential","magneticField"]
	    }
	},
        "solid":
	{
            "Exports":
            {
		"fields":["displacement","Von-Mises","tresca","principal-stresses","material-properties"]
	    }
	},
        "thermo-electric":
	{
            "Exports":
            {
		"fields":["heat.temperature","electric.electric-potential","electric.current-density"]
	    }
	},
        "electric":
	{
	    "Save":
	    {
		"Fields":
		{
		    "names":["electric-potential"]
		}
	    },
	    "Measures":
	    {
		"Points":
		{
		    "%1_1%":
		    {
			"coord":"%1_2%",
			"fields":"electric-potential",
			"index1": [ ["V0", "{-21.75e-3,0.e-3,-421.15e-3}"],
                		    ...
				  ]
		    }
		},
		"Statistics":
		{
		    "Intensity0":
		    {
			"type":"integrate",
			"expr":"-electric_iL1_sigma*electric_dnP:electric_iL1_sigma:electric_dnP",
			"markers":"Inner1_LV0"
		    },
		    "Intensity1":
		    {
			"type":"integrate",
			"expr":"-electric_oL2_sigma*electric_dnP:electric_oL2_sigma:electric_dnP",
			"markers":"OuterL2_LV0"
		    },
                    "Power_%1_1%":
                    {
                        "type":"integrate",
                        "expr":"electric_%1_1%_sigma*(electric_dxP^2+electric_dyP^2+electric_dzP^2):electric_%1_1%_sigma:electric_dxP:electric_dyP:electric_dzP",
                        "markers":"%1_2%",
			"index1":[ ["H1", "H1_Cu"],
				   ...
                                 ]
                    }
		}
	    }
	},
	"heat":
	{
	    "Save":
	    {
		"Fields":
		{
		    "names":["temperature"]
		}
	    },
	    "Measures":
	    {
		"Points":
		{
		    "%1_1%":
		    {
			"coord":"%1_2%",
			"fields":"temperature",
			"index1": [ ["T0", "{-3.554e-3,-33.8174e-3,-118e-3}"],
                		    ["T1","{-5.4752e-3,34.5691e-3,135e-3}"]
				  ]
		    }
		},
		"Statistics":
		{
		    "MeanT":
		    {
			"type":["min","max","mean"],
			"field":"temperature"
		    },
		    "MeanT_%1_1%":
		    {
			"type":["min","max","mean"],
			"field":"temperature",
			"markers":["%1_2%","%1_3%","%1_4%"],
			"index1":[ ["Couple1", "H1_Cu", "R1", "H2_Cu" ],
				   ...
				 ]
		    },
		    "MeanT_%1_1%":
		    {
			"type":["min","max","mean"],
			"field":"temperature",
			"markers":"%1_2%",
			"index1":[ ["H1", "H1_Cu"],
				   ...
				 ]
		    },
		    "Flux_%1_1%":
		    {
			"type":"integrate",
			"expr":"%1_2%*(heat_T-(%1_3%+%1_4%/2.)):heat_T:%1_2%:%1_3%:%1_4%",
			"markers":"%1_1%",
			"index1":[ ["Channel0", "h0", "Tin", "dTw0"],
				   ...
				 ]
		    }
		}
	    }
	}
    }

3.3. Examples