Untitled :: HiFiMagnet Documentation

1. HiFiMagnet Salome Plugin

Welcome to HiFiMagnet Salome Plugin documentation!

The HiFiMagnet Salome Plugin documentation describes its installation, its features, its uses and provides some references.

2. Introduction

The HiFiMagnet Salome Plugin allows to easily:

define CAD geometry for Solenoidal High Field Magnet,
mesh these geometries,
provide a template for HiFiMagnet simulation setup.

In a near future, the plugin will also provides tools:

to run calculations either locally or remotely,
to analyze the results

Supported Salome versions are: from 9.2.0 to 9.5.0
The meshing features require a license to MeshGems suite.
Salome docker image without HiFiMagnet plugin can be found on this dockerhub.

To use Salome in GUI mode the docker container should contain appropriate graphics drivers supporting OpenGL 4.5.

3. Quick Starts

This document will illustrate how to simply use HiFiMagnet Salome plugin and give examples for most common operations.

Custom installation, eg. for native installation, is detailed in the dev section.

3.1. Salome plugin matrix

Native

Docker Container

Singularity Container

Note

SALOME-9.5.0-UB20.04.tgz

Designed for Ubuntu 20.04

On Windows 10 requires WSL2 Ubuntu 20.04 and MobaXterm for GUI mode

feelpp/salome:9.5.1

salome-hifimagnet-9.5.1.sif

singularity 3.2 and later

salome-hifimagnet-9.5.1.simg

for singularity 2.6

3.2. Getting HiFiMagnet Salome plugin

They are several way to use HiFiMagnet Salome plugin. The easiest way is to use container, either Docker based or Singularity based. If your system support singularity containers we recommend to use them instead of Docker ones.

3.3. Running HiFiMagnet Salome plugin

HiFiMagnet Salome plugin can be run either in GUI or TUI mode. TUI stands for Terminal User Interface.

To switch to TUI mode, use -t option. Add -b option to the use TUI in batch mode.

In the sequel, we use the classical Unix notation for command. In peculiar […] denotes optional argument.

3.3.1. from Singularity container

Assuming we use salome.simg singularity image:

singularity exec [--nv] \
  [-H $HOME:/home/$USER] \
  -B $STORE/DISTENE/DLim:/opt/DISTENE/DLim:ro \
  salome.simg \
  salome -w1 [-t -b] ...

where:

$STORE/DISTENE/DLim is the directory on the host containing a valid dlim8.key license file. You need to adapt this to your configuration.

the --nv flag is mandatory to run in GUI mode and is only supported by nvidia drivers. For other graphic video card, use mesa_salome instead of salome
On Lncmi server option -H $HOME:/home/$USER may be dropped

To check your graphic video card on Debian/Ubuntu you may use inxi -G.
You may use a relative or absolute path for the image salome.simg.

3.3.2. from Docker container

xhost local:root
docker run -ti --rm -e DISPLAY \
   --net=host --pid=host --ipc=host \
   --env QT_X11_NO_MITSHM=1 \
   -v /tmp/.X11-unix:/tmp/.X11-unix \
   -v $HOME/.Xauthority:/home/feelpp/.Xauthority \
   -v $STORE/DISTENE/DLim:/opt/DISTENE/DLim:ro \
   feelpp/salome:9.5.1 salome [-t -b] ...

where:

$STORE/DISTENE/DLim is the directory containing a valid dlim8.key license file.

You have to be a member of feelpp team in dockerhub to have access to the docker image.

On Windows:

Start MobaXterm (that provides a running X11 server)
Then run:

docker run -it --rm -e DISPLAY :0 feelpp/salome:9.5.1

On MacOs X:

start XQuartz
In XQuartz: defaults write org.macosforge.xquartz.X11 enable_iglx -bool true
Restart XQuartz
Then run:

ip=$(ifconfig en0 | grep inet | awk '$1=="inet" {print $2}')
xhost +$ip
docker run -it --rm -e DISPLAY $ip:0 feelpp/salome-9.5.1

You may need to adapt the line to get the working ip of your machine depending on your internet connection.

See this presentation for details

3.3.3. Main commands

We will omit the part of the command related to the use of Singularity or Docker to only give the Salome command. If you plan to run these commands from a Singularity or Docker image, just start the container (see here, watch out to not forget to enable the display if you want to use the GUI mode).

Examples files may be found here.

The structure of the yaml file describing the geometry and mesh be generated will be described in the data structure section.

Generation of an Insert CAD with eventually an air box in TUI mode

salome [-m GEOM,SMESH,HIFIMAGNET] [-t -b] \
   $HIFIMAGNET/HIFIMAGNET_Cmd.py \
   args:--cfg=Insert-H1H4-Leads-2t.yaml[,--air,--infty_Rratio=2,--infty_ZRatio=1.5][,--mesh,--groupIsolant,--groupCoolingChannels,--groupLeads]

$HIFIMAGNET is the install directory of HiFiMagnet Salome plugin, eg /opt/SALOME-9.5.0-UB18.04/INSTALL/HIFIMAGNET/bin/salome.

A 4 helix insert with sourring air (in transparent red)

An example Insert-H1H4-Leads-2t.yaml can be found in /usr/local/share/salome/H1H4 in singularity images.
If you are using containers, the shell command above is to be executed within the container. The container shall be launched from the directory that holds the yaml file you will use in the shell command.

Building CAD for an insert may require a long long time and a large amount of RAM. Thus it is adviced to run the CAD generation within a screen session on an appropriate machine (eg. Lncmi servers for Lncmi user).

Moreover, it is also adviced to run first the CAD generation for the insert, then add the air and finally mesh. Avoid trying to build CAD and Mesh at once.

4. Data Structure

An insert consists in a set of:

helices,
connection rings

and eventually an inner and an outer currentLead.

Each structure is defined as a yaml file.

The yaml files for helices are generated from the insert optimized geometry insert.d by running opt2yml. Similarily, the helical cut files are obtained by running opt2cad. Please refer to here for details.

The generated files still need some user intervention to be complete - namely dimension of the cylnder tube has to be added manually. Check with the Bureau d’etudes for these dimensions

As for Rings and CurrentLeads, the files must be generated manually.

4.1. helix structure

An helix is actually a cylindrical tube which exhibit a single or double helical cut made by EDM. The path of the helical cut is provided in a separate file: *_cut_salome.dat if no shapes are added to the helical cut, or *_cut_with_shapes_salome.dat otherwise. The *_cut[_with_shapes]_salome.dat file are generated from the optimized geofile .d describing the axisymetrical geometry using opt2cad and eventually add_shape. See here for details.

!<Helix>
name: HL-31_H1 (1)
dble: true (2)
odd: true (3)
r: (4)
  - 19.3
  - 24.2
z: (5)
  - -226
  - 108
cutwidth: 0.22 (6)
axi: !<ModelAxi> (7)
  ...
m3d: !<Model3D> (8)
  ...
shape: !<Shape> (9)
  ...

1	name of the CAD to be created (must begin with an "H").
2	specify if the helix is single or double (ie. helical cut).
3	specify if the helix is odd or even (the helical cut patch orientation changes from one helix to the other).
4	the radial dimension in mm.
5	the axial dimension in mm.
6	the width of the helical cut.
7	the corresponding axi model section.
8	the ………… 3d model section.
9	definition of the shape added along the helical path

4.1.1. `axi` structure

The axi structure defines the helical cut along with the file *_cut_salome.dat

axi: !<ModelAxi>
  name: "HL-31.d" (1)
  h: 86.51 (2)
  pitch: (3)
    - 17.302
  turns: (4)
    - 10

1	name of the axisymetrical description of the magnet (see magnettools)
2	half electrical length; $2h$ corresponds to the axial length of the helical path centered on the origin.
3	list of pitch $p_i$
4	list of turns $n_i$

The helical path consists in a set of $i$ helices with a pitch $p_i$ and a number of turns $n_i$

4.1.2. `m3d` structure

m3d: !<Model3D>
  cad: "HL-31-202MC" (1)
  with_shapes: false (2)
  with_channels: false (3)

1	name of the CAD geometry (usually stems from the Bureau d’Etudes nomemclature to keep track of the CADs)
2	indicates wether shapes are added or not on the helical path
3	indicates wether micro-cooling channels are added (only for radial helices)

4.1.3. `shape` structure

shape: !<Shape>
  name: (1)
  profile: "" (2)
  length: 0 (3)
  angle: [0] (4)
  onturns: 0 (5)
  position: ABOVE (6)

1	name of the shape to be added
2	name of CAD profile (Actually the name of the shape file description without extension aka `.dat`; the name is build as `Shape_CADID` where `CADID` comes from the Bureau d’Etudes nomemclature to keep track of the CADs; )
3	list of angular length of the shape in degree
4	list of angular shift between 2 consecutive shapes (optionnal)
5	list of turn number on which the shape are disposed
6	orientation of the shape (values valid are …)

The shape file description is a simple .dat file that defines the number of points of the shape and theirs coordinates in a local cartesian frame:

#Shape : HL-31-985 pour H14
#N_i
20
#X_i F_i
-3.75	0
...
 3.75	0

Data in this section are just given for the records. They are not used for building the helical cut of the attached helix. In future versions, it is planned to use these data to eventually build the helical cut if needed. So please kind the data synced with the actual configuration.

4.1.4. `helical cut` structure

The geometry of the helical cut is computed using MagnetTools. It provides the coordinates of the cut in developed form which will be mapped onto the outer cylinder boundary of an helix.

# Fichier de decoupe Salome V7.3.0, (1)
# Fichier d'Optimisation [Aubert] : HL-31_H1_.d
# author: trophime
# date : Tue Sep 30 13:32:59 2014
#
# Orientation : gauche

#theta[rad] 	Shape_id[]	Z[mm], (2)
#
-0.00000000e+00	           0	8.65100000e+01
-1.83673270e+00	           0	7.78590000e+01
...
-5.15703414e+01	           0	-7.78590000e+01
-5.34070738e+01	           0	-8.65100000e+01

1	header
2	`theta`, `Z_i` defines the coordinates of the point in a 2D cartesian frame (note: $\text{theta} \in [0,2\pi*n_{turns}$] with $n_{turns}$ the total number of turn of the path) and `Shape_id` indicates the precense or absence of shape and eventually of micro-cooling channel

4.2. Ring

A ring ensure the electrical and mechanical connection between 2 consecutive helices. It is a cylinder eventually with $n$ cylindrical slots, disposed at regular angular interval $angle$ in it to ensure a proper cooling of the connected helices.

!<Ring>
name: Ring-H1H2 (1)
BPside: true (2)
r: [19.3, 24.2, 25.1, 30.7] (3)
z: [0, 20] (4)
fillets: false (5)
n: 6
angle: 46

1	name of the CAD to be created (must begin with "R")
2	specifiy the position of the ring: either on Low pressure (eg `BPside=true`) or High Pressure side (eg `BPside=false`)
3	the radial dimension in mm.
4	the axial dimension in mm.
5	indicates the presence or the absence of cylindrical slot

4.3. CurrentLeads

4.3.1. Inner Lead

In general, the inner current lead is made of a cylinder in which $n_holes$ rectangular windows are cut. If the dimensions of the first helix and the inner lead do not match, there is an additional part to make the connection between the current lead and the helix. For sake of simplicity, this part , refered as support, has been "incorporated" into the lead.

!<InnerCurrentLead>
name: Inner (1)
r: [19.3, 24.2] (2)
h: 480.0 (3)
fillet: 0 (4)
holes: [123, 12, 90, 60, 45, 3] (5)
support: [] (6)

1	name of the CAD to be created (must begin with an "I")
2	list of radius (inner, outer)
3	height of the current lead
4	indicator for building fillet (0 for false, 1 for true)
5	characteristic for fixing holes ([H_Holes, Shift_from_Top, Angle_Zero, Angle, Angular_Position, $n_holes$])
6	characteristic for the support ([R2, DZ])

4.3.2. Outer Lead

Outer current lead consists in an assembly of an connection ring and 2 sets of 3 bars with rectangular cross-section $dx \times dy$. The support correspond to the small part that make the connection between the ring and the bars. The support is made of 6 parallelepiped disposed at regular angular interval $d\alpha$

!<OuterCurrentLead>
name: Outer (1)
r: [19.3, 24.2] (2)
h: 10 (3)
support: [10, 5, 40, 45] (4)
bar: [4, 9, 5, 501] (5)

1	name of the CAD to be created (must begin with an "O")
2	list of radius (inner, outer)
3	height of the current lead
4	characteristic of the support (DX0, DZ, $d\alpha$, $\alpha_0$ the angular shift)
5	characteristic of the bar (R, $dx$, $dy$, $L$ the length of the bar)

There are some requirements on the total length of the inner and outer current lead. Indeed, when the CAD for the insert we arbitrary requires that the bottom of the inner and outer lead have the same z coordinates.

4.4. Insert

!<Insert>
name: "HL-31", (1)
Helices:, (2)
  - HL-31_H1
  ...
Rings:, (3)
  - Ring-H1H2
  ...
CurrentLeads:, (4)
  - inner
  - outer-H14
innerbore: 18.54, (5)
outerbore: 186.25, (6)
HAngles:, (7)
RAngles:, (8)

1	name of the CAD geometry
2	list of helices
3	list of rings
4	define inner and outer current leads
5	radius of the inner bore tube
6	radius of the external tube holding the helices insert
7	angular orientation of helices (optionnal)
8	angular orientation of rings (optionnal)

The radius of the external tube <5> may not correspond to the real radius of the part. Indeed, this part is in general not a simple cylinder. To model the cooling of this part, we compute the assiocated hydraulic diameter $d_h$ as the ratio of the section of the last cooling chanel over the wetted perimeter. The radius of the equivalent external tube is then set to:

\[r_{outer} = r_H + d_h/2.\]

with $r_H$ the outer radius of the antepenultiemen helix.

4.5. Mesh

The mesh is generated from the command line when the option --mesh is passed to salome. The first time the mesh is generated, a file , namely Insert_meshdata.yaml where Insert.yaml is the actual yaml cfg file used in the main command line, is also created containing main mesh parameters. This file may be later used to regenerate the same mesh or modify to get a finner or coarser mesh.

So far only MeshGems mesher is supported.

Here is an example of the yaml cfg file:

!<MeshData>
geometry: BancMesure_H3H4, (1)
name: BancMesure_H3H4-air, (2)
algosurf: BLSURF, (3)
algovol: GHS3D, (4)
Gradation: 1.05, (5)
KeepFiles: 0, (6)
MakeGroupsOfDomains: 0, (7)
OptimizationLevel: 4, (8)
RemoveLogOnSuccess: 1, (9)
MaximumMemory: 450559, (10)
surfhypoths:, (11)
- - - HL-31_H3_inputs
    - [2, 1, 2.16, 0.65, 65.0, 1.546]
  - - HL-31_H3_boundary
    - [2, 1, 2.16, 0.65, 65.0, 1.546]
  - - HL-31_H3_interface
    - [2, 1, 0.72, 0.065, 6.5, 0.1546]
  - - HL-31_H3_iboundary
    - [2, 1, 0.72, 0.065, 6.5, 0.1546]
  - - HL-31_H3_others
    - [2, 1, 2.16, 0.65, 65.0, 1.546]
- - - HL-31_H4_inputs
    - [2, 1, 2.43, 0.729, 72.99, 1.90]
  - - HL-31_H4_boundary
    - [2, 1, 2.43, 0.729, 72.9, 1.90]
  - - HL-31_H4_interface
    - [2, 1, 0.81, 0.0729, 7.29, 0.190]
  - - HL-31_H4_iboundary
    - [2, 1, 0.81, 0.0729, 7.29, 0.190]
  - - HL-31_H4_others
    - [2, 1, 2.43, 0.729, 72.9, 1.90]
- - - Ring-H3H4_H1
    - [2, 1, 2.16, 0.65, 65.0, 1.546]
  - - Ring-H3H4_H2
    - [2, 1, 2.43, 0.729, 72.9, 1.90]
  - - Ring-H3H4_cooling
    - [2, 1, 4.89, 1.469, 146.9, 1.546]
  - - Ring-H3H4_boundary
    - [2, 1, 4.89, 1.46, 146.9, 1.546]
- - - Air_inner
    - [2, 1, 2.16, 0.65, 65.0, 1.546]
  - - Air_inputs
    - [2, 1, 3.86, 0.925, 926.0, 176.85]
  - - Air_infty
    - [2, 1, 3.86, 0.925, 926.0, 176.85]
volhypoths: []

1	name of the CAD geometry without extension
2	basename of the output mesh
3	mesh algorithm used for surfacic meshes
4	mesh algorithm used for volumic meshes
5	maximum ratio between the lengths of two adjacent edges.
6	allows checking input and output files of MG-Tetra software, while usually these files are removed after the launch of the mesher. The log file (if any) is also kept if this option is `1`.
7	allows grouping volumes into domains
8	allows choosing the required optimization level (higher level of optimization provides better mesh, but can be time-consuming); values are 1: none, 2: light, 3: medium (standard), 4: standard+, 5: strong
9	removes or not files upon mesh completion
10	launches MG-Tetra software with work space limited to the specified amount of RAM, in Mbytes. If this option is checked off, the software will be launched with 7O% of the total RAM space.
11	list of input data for the surfacic mesher provided for each boundary group defined in the CAD geometry

The input data for the surfacic mesher (or hypothesys in Salome formalism) are defined as follows:

surfhypoths:
- - - Boundary_Name, (1)
    - [2, 1, physsize, minsize, maxsize, chordalerror], (2)
  ...

1	the name of the consider boundary group
2	the actual hypothesis are: `2` for `1` for `physsize` for setting the requested element size in mm `minsize` for setting the minimum allowed element size in mm `maxsize` for setting the maximum allowed size in mm `chordalerror` for setting the requested chordalerror size in mm

The chordalerror is the maximum desired distance between a triangle and its supporting CAD surface. The smaller this distance is, the closer the mesh is to the exact surface (only available in isotropic meshing).

4.6. Advanced mesh options

The mesh can customized using the yaml cgf file presented above. There are also some options to reduce the number of surfacic meshes that will be latter use to apply boundary conditions:

--hideIsolant: to discard non-electric conducting domains (aka glue or insulators),
--groupIsolant: to group glue or insulators per helix as one domain,
--groupCoolingChannels: to group Cooled surfaces per cooling channels,
--groupLeads: to group the domains for currentleads into a single domain for inner and and a single domain for outer lead.

A --coarse option may be used to generate a quite coarse mesh.

These options are available in the main command line.

For most simulations, we use --groupIsolant, --groupCoolingChannels and --groupLeads. For HDG models, as the insulators are not considered in the simulation so far, we add --hideIsolant to ignore the non-electric conducting domains.

5. Generate Templates setup for HiFiMagnet simulations

Add --setup option to the command line to generate template files required for the setup of HiFiMagnet simulations.

Generation of template cfg and json files

salome [-m GEOM,SMESH,HIFIMAGNET] [-t -b] \
   $HIFIMAGNET/HIFIMAGNET_Cmd.py \
   args:--cfg=Insert-H1H4-Leads-2t.yaml[,--air,--infty_Rratio=2,--infty_ZRatio=1.5],--setup

6. Using Salome for Checking and/or Debugging

Salome is an open-source generic platform for Pre- and Post-Processing for numerical simulation. More details can be found in basis Salome usage.

To view:

the generated CAD, just follow instructions in this section,
the generate mesh, just follow instructions in this section,

To debug: to be done

1	name of the axisymetrical description of the magnet (see magnettools)
2	half electrical length; \(2h\) corresponds to the axial length of the helical path centered on the origin.
3	list of pitch \(p_i\)
4	list of turns \(n_i\)