SFEMaNS  version 4.1 (work in progress) Reference documentation for SFEMaNS
Data file

The data file contains information on the problem approximated with the code SFEMaNS. These informations are stocked in a derived data type called inputs. For example, the kinetic Reynolds number is saved in inputs%Re. It is possible to add variable, not already included in SFEMaNS, with the file read_user_data.f90. Such new variables are stocked in the derived data type called user. We refer to the section Fortran file read_user_data.f90 for more information. The information read by the code SFEMaNS can be splitted in the following groups.

1. General settings (mesh, number of Fourier modes, equations approximated, etc.).
2. Setting for the Navier-Stokes equations.
3. Setting for the level set equation.
4. Setting for the temperature equation.
5. Setting for the Maxwell equations.
6. Setting for eigenvalue problems with Arpack.
7. Setting for the outputs computations.
8. Setting to force Fourier components of the velocity field and the magnetic field to zero.

The following described the datas associated to each of the above groups. In particular, we show how to set these datas and specify if it is required to set them. Indeed, some variables have default value while other need to be set in the data for any problem considered. We note that many examples of data files are described in the sections Examples with manufactured solutions and Examples on physical problems.

Remarks:

1. The set of each data is done in the line under its associated key line. These key lines always start with "===".
2. The datas associated to an equation are not required if this equation is not solved.

# General settings

1. The format of the mesh (formatted or unformatted) is set as follows.
===Is mesh file formatted (true/false)?
2. The directory and the name of the mesh file is set as follows.
===Directory and name of mesh file
3. It is possible to point out that the mesh is symmetric with the following option.
===Is the mesh symmetric (true/false)?
This parameter is set to false by default.
4. The number of processors in the meridian section has to be set.
===Number of processors in meridian section
The finite element meridian section is then splitted in as many subsections.
5. The number of processors in the Fourier space has to be set.
===Number of processors in Fourier space
6. The number of Fourier modes used to approximate the problem is set as follows.
===Number of Fourier modes
Remark: the number of Fourier mode is a multiple of the number of processors in Fourier space. For instance if one use two processors in Fourier space and approximate four Fourier modes, each processor in Fourier space is approximating the equations for two Fourier modes. The total number of processors used is equal to the number of precessors in meridian section times the number of processors in Fourier space.
7. It is possible to select a given list of Fourier mode as follows.
===Select Fourier modes? (true/false)
This parameter is set to false by default.
8. If the above parameter is true, the list of Fourier modes approximated has to be given.
===List of Fourier modes (if select_mode=.TRUE.)
9. Four type of problems can be considered: nst (hydrodynamic), mxw (magnetic), mhd (magnetohydrodynamic) and fhd (ferrohydrodynamic). The problem type is set as follows.
===Problem type: (nst, mxw, mhd, fhd)
The answer is either 'nst', 'mxw' , 'mhd' or 'fhd'.
10. The user has to specify if a restart is done on the velocity field.
===Restart on velocity (true/false)
11. It is also possible to do a restart with data of the magnetic field or the temperature.
===Restart on magnetic field (true/false)
===Restart on temperature (true/false)
These parameters are set to false by default.
12. It is possible to use the metis partition of a previous computation.
===Do we read metis partition? (true/false)
This parameter is set to false by default. If a restart is done, set this parameter to true. Indeed, the metis partition contains the information on the splitting of the finite element section in subsections.
13. The number of time step and the number of time iterations is set as follows.
===Time step and number of time iterations

Remark: when doing a restart, the name of the restart files used should not display information on the time iteration they had been generated. It means the part _I001 (_I002, etc.) should be removed of their name. See below for more information on the generation of the restart files.

# Setting for periodic problem (optional)

1. The number of pairs of boundaries with periodic condition is set as follows.
===How many pieces of periodic boundary?
This parameter is set to zero by default.
2. If pieces of periodic boundary are present, the label of the boundaries and the vector that lead to the first boundary to the second one are given after the following line.
===Indices of periodic boundaries and corresponding vectors
We note that the code needs as much as lines as the number of pairs of boundaries with periodic condition.

# Setting for the Navier-Stokes equations

We refer to the section Hydrodynamic setting for details on the weak formulation of the Navier-Stokes equations.

## General settings

To approximate solutions of the Navier-Stokes equations, set the following parameters.

1. The dependent variable is either the velocity field or the momentum.
===Solve Navier-Stokes with u (true) or m (false)?
It is set to true by default. We note that the momentum has to be used for multiphase flow problem.
2. Number of subdomains where the Navier-Stokes equations are approximated.
===Number of subdomains in Navier-Stokes mesh
3. List of the above subdomains.
===List of subdomains for Navier-Stokes mesh
4. Number of boundary pieces with Dirichlet condition.
===How many boundary pieces for full Dirichlet BCs on velocity?
5. List of the boundary pieces with Dirichlet condition.
===List of boundary pieces for full Dirichlet BCs on velocity
6. Number of boundary pieces with homogeneous Neumann condition.
===How many boundary pieces for homogeneous normal velocity?
7. List of the boundary pieces with homogeneous Neumann condition.
===List of boundary pieces for homogeneous normal velocity
8. Penalty coefficient for enforcing homogeneous Neumann boundary velocity.
===stab_bdy_ns
It is set to one by default.
9. Kinetic Reynolds number $$\Re$$.
===Reynolds number
10. Penalty coefficient $$c_\text{div}$$, see the section Approximation of the Navier-Stokes equations.
===Coefficient for penalty of divergence in NS?
It is set to zero by default. It can not be used with the momentum as dependent variable.

## Precession

SFEMaNS can consider precession set up in the precession frame when the rotation axis is the vertical axis $$\textbf{e}_z$$. The method consists of adding the term $$2 \epsilon \textbf{e}_p \times \bu$$ in the left handside of the Navier-Stokes equations. The parameter $$\epsilon$$ is the precession rate. The vector $$\textbf{e}_p$$ is equal to $$\sin(\alpha\pi)\cos(\theta) \textbf{e}_r -\sin(\alpha\pi)\sin(\theta)\textbf{e}_\theta+\cos(\alpha\pi)\textbf{e}_z$$ with $$\alpha$$ the angle of precession, i.e. the angle between the vertical axis and the precession axis. To use this feature, set the following parameters.

1. Is the precession term computed?
===Is there a precession term (true/false)?
It is set to false by default.
2. Precession rate $$\epsilon$$.
===Precession rate
3. Precession angle $$\alpha$$ in degree.
===Precession angle over pi

## Non axisymmetric solid obstacle

SFEMaNS can consider non axisymmetric geometry via the use of a penalty method, see the section Extension to non axisymmetric geometry for more details. To use this feature, set the following parameters.

1. Is the penalty method used?
===Use penalty in NS domain (true/false)?
It is set to false by default. If set to true, the penalty function $$\chi$$ is defined in the subroutine penal_in_real_space of the file condlim.f90.
2. Does the solid has a nonzero velocity?
===Use nonzero velocity in solids (true/false)?
It is set to false by default. If set to true, the velocity $$\bu_\text{obs}$$ is defined in the subroutine imposed_velocity_by_penalty of the file condlim.f90.
3. Should the code compute the following quantity $$\displaystyle -\frac{2}{\pi}\int_{\Omega_{c,f}} \frac{(1-\chi)(\bu-\bu_\text{obs}) \cdot \textbf{e}_z}{\tau}$$ with $$\tau$$ being the time step.
===Compute z momentum (true/false)?
It is set to false by default. The output is written in the file fort.12 each inputs%freq_en time iterations with inputs%freq_en the frequency to write energy outputs (defined later).

## LES stabilization with entropy viscosity

We refer to the section Entropy viscosity for under resolved computation for a description of this method. To use this stabilization method, set the following parameters.

1. Is the entropy viscosity (LES) used?
===Use LES? (true/false)
It is set to false by default.
2. Coefficient $$c_\text{e}$$.
===Coefficient multiplying residual
3. Optional coefficient $$c_1$$.
===Coefficient for explicit LES
It is set to zero by default.

## Multiphase computations

We refer to the section Extension to multiphase flow problem for more details on this set up.

To use this feature, set the following parameters.

1. Do we use a second order in time algorithm (BDF2)?
===Do we solve momentum with bdf2 (true/false)?
It is set to false by default. Theoretical results about the algorithm's stability are only known for BDF1.
2. Is the momentum equation stabilized with the entropy viscosity?
===Use LES in momentum? (true/false)
It is set to true by default.

## Informations for the Navier-Stokes equations solvers

### Velocity solver

Set the following information on the solver for the velocity field.

1. Maximum of iterations.
===Maximum number of iterations for velocity solver
2. Relative tolerance.
===Relative tolerance for velocity solver
3. Absolute tolerance.
===Absolute tolerance for velocity solver
4. Type of solver.
===Solver type for velocity (FGMRES, CG, ...)
It is possible to set it to GMRES (Generalized Minimal Residual method), FGMRES (Flexible Generalized Minimal Residual method) and CG (Conjugate Gradient method).
5. Type of preconditionner.
===Preconditionner type for velocity solver (HYPRE, JACOBI, MUMPS...)

### Pressure solver

Set the following information on the solver for the pressure.

1. Maximum of iterations.
===Maximum number of iterations for pressure solver
2. Relative tolerance.
===Relative tolerance for pressure solver
3. Absolute tolerance.
===Absolute tolerance for pressure solver
4. Type of solver.
===Solver type for pressure (FGMRES, CG, ...)
It is possible to set it to GMRES (Generalized Minimal Residual method), FGMRES (Flexible Generalized Minimal Residual method) and CG (Conjugate Gradient method).
5. Type of preconditionner.
===Preconditionner type for pressure solver (HYPRE, JACOBI, MUMPS...)

### Mass matrix solver

Set the following information on the solver for the mass matrix.

1. Maximum of iterations.
===Maximum number of iterations for mass matrix solver
2. Relative tolerance.
===Relative tolerance for mass matrix solver
3. Absolute tolerance.
===Absolute tolerance for mass matrix solver
4. Type of solver.
===Solver type for mass matrix (FGMRES, CG, ...)
It is possible to set it to GMRES (Generalized Minimal Residual method), FGMRES (Flexible Generalized Minimal Residual method) and CG (Conjugate Gradient method).
5. Type of preconditionner.
===Preconditionner type for mass matrix solver (HYPRE, JACOBI, MUMPS...)

# Setting for the level set equations (multiphase problem)

We refer to the section Extension to multiphase flow problem for a description of such set ups.

## General settings

To consider multiphase flow problems, set the following parameters.

1. Is a level set used?
===Is there a level set?
It is set to false by default. The following information are only read if it is set to true.
2. What is the number of fluids?
===How many fluids?
As the level set functions represent interfaces between fluids, this number is equal to the number of level set plus one.
3. Define a multiplier that multiplies the minimum mesh size. The result is saved in inputs%h_min_distance. It can be used to initialize the level set.
===multiplier for h_min for level set
4. Coefficient $$c_\text{comp}\in[0,1]$$.
===Compression factor for level set
A typical value is one.
5. Densities of the different fluids.
===Density of fluid 0, fluid 1, ...
6. Dynamical viscosities of the different fluids.
===Dynamic viscosity of fluid 0, fluid 1, ...
7. If needed, set the electrical conductivity of the different fluids.
===Conductivity of fluid 0, fluid 1, ...
8. Is there surface tension effect?
===Is there a surface tension?
The default value is false.
9. Coefficients of surface tension of each level set. These parameters are the inverse of the Weber number.
===Coefficients of surface tension for level set 0, level set 1, ...
10. Is a mass correction applied?
===Do we apply mass correction? (true/false)
It is set to true by default.
11. Number of boundary pieces with Dirichlet condition.
===How many boundary pieces for Dirichlet BCs on level set?
12. List of the boundary pieces with Dirichlet boundaries conditions.
===List of boundary pieces for Dirichlet BCs on level set
13. What function of reconstruction $$F$$ is used?
===How are the variables reconstructed from the level set function? (lin, reg)
If $$F$$ is the identity set it to 'lin', set it to 'reg' otherwise.
14. Coefficient $$c_\text{reg}$$ for reg reconstruction.
===Value of the regularization coefficient in (0,0.5]
If used, it is generally set to $$0.5$$.
15. When reconstructing the fluid properties with the function $$F$$, do we use $$F(\tilde{\phi})$$ with $$\tilde{\phi}=\min(1,\max(0,\phi))$$?
===Do we kill level set overshoot? (true/false)
This parameter is set to false by default. It allows to ensure that the density does not present overshoot.

## Information for the level set equation solver

Set the following information on the solver for the level set equation.

1. Maximum of iterations.
===Maximum number of iterations for level set solver
2. Relative tolerance.
===Relative tolerance for level set solver
3. Absolute tolerance.
===Absolute tolerance for level set solver
4. Type of solver.
===Solver type for level set (FGMRES, CG, ...)
It is possible to set it to GMRES (Generalized Minimal Residual method), FGMRES (Flexible Generalized Minimal Residual method) and CG (Conjugate Gradient method).
5. Type of preconditionner.
===Preconditionner type for level set solver (HYPRE, JACOBI, MUMPS...)

# Setting for the temperature equation

We refer to the section Heat equation's weak formulation for details on the weak formulation of the heat equation.

## General settings

To consider thermal effect, set the following parameters.

1. Is there thermal effect?
===Is there a temperature field?
The default value is false. The following information are only read if it is set to true.
2. The number of subdomains where the heat equation is solved.
===Number of subdomains in temperature mesh
3. The list of the subdomains where the heat equation is solved.
===List of subdomains for temperature mesh
4. The volumetric heat capacity $$C$$ in each domains.
===Volumetric heat capacity (1:nb_dom_temp)
5. The thermal conductivity $$\lambda$$ in each domains.
===Thermal conductivity (1:nb_dom_temp)
6. It is possible to approximate the heat equation with the diffusivity coefficient $$\kappa=\frac{\lambda}{C}$$.
===Diffusivity coefficient for temperature (1:nb_dom_temp)
In that case, the equations solved is $$\partial_t T + \DIV(T\bu)-\DIV(\kappa\GRAD T)=0$$.
7. Nondimensional gravity coefficient that be used to define the action of the temperature of the velocity field.
===Non-dimensional gravity coefficient
This parameter is saved in inputs%gravity_coefficient.
8. Number of boundary pieces with Dirichlet boundary condition.
===How many boundary pieces for Dirichlet BCs on temperature?
9. List of the boundary pieces with Dirichlet boundary condition.
===List of boundary pieces for Dirichlet BCs on temperature
10. Number of interfaces between the velocity field and the temperature field domains.
===Number of interfaces between velocity and temperature only domains (for nst applications)
11. List of interfaces between the velocity field and the temperature field domains.
===List of interfaces between velocity and temperature only domains (for nst applications)

## Information for the temperature equation solver

Set the following information on the solver for the temperature equation.

1. Maximum of iterations.
===Maximum number of iterations for temperature solver
2. Relative tolerance.
===Relative tolerance for temperature solver
3. Absolute tolerance.
===Absolute tolerance for temperature solver
4. Type of solver.
===Solver type for temperature (FGMRES, CG, ...)
It is possible to set it to GMRES (Generalized Minimal Residual method), FGMRES (Flexible Generalized Minimal Residual method) and CG (Conjugate Gradient method).
5. Type of preconditionner.
===Preconditionner type for temperature solver (HYPRE, JACOBI, MUMPS...)

# Setting for the Maxwell equations

We refer to the section Magnetic setting for details on the weak formulation of the Maxwell equations.

## General settings

The parameters required to approximate solutions of the Maxwell equations can be splitted in two main groups.

1. Information on the approximation of the magnetic field in the conducting domain.
1. The dependent variable in the conducting region can be $$\bH$$ or $$\bB$$.
===Solve Maxwell with H (true) or B (false)?
It is set to false by default. When using a magnetic permeability that depends of the time and the azimuthal direction, it has to be set to false.
2. Number of conducting subdomains where the Maxwell equation is approximated with the magnetic field $$\bH$$ or $$\bB$$.
===Number of subdomains in magnetic field (H) mesh
3. List of the conducting subdomains.
===List of subdomains for magnetic field (H) mesh
4. Number of interfaces in the conducting domains.
===Number of interfaces in H mesh
These interfaces represents surfaces with jump in the magnetic permeability or surfaces where boundary conditions are applied on the velocity field or the temperature field.
5. List of the above interfaces.
===List of interfaces in H mesh
6. Number of boundary pieces with Dirichlet conditions on $$\bH\times\textbf{n}$$.
===Number of Dirichlet sides for Hxn
7. List of the boundary pieces with Dirichlet condition.
===List of Dirichlet sides for Hxn
8. Is the magnetic permeability defined analytically?
===Is permeability defined analytically (true/false)?
It is set to false by default. If set to true, the magnetic permeability is defined in a function of the file condlim.f90.
9. If the magnetic permeability is defined analytically, does it depends of the time and the azimuthal direction?
===Is permeability variable in theta (true/false)?
It is set to false by default and the magnetic permeability is defined in the function mu_bar_in_fourier_space of the file condlim.f90. If set to true, this function defined the stabilization term $$\overline{\mu}$$ and the magnetic permeability is defined in the function mu_in_real_space.
10. Is the magnetic permeability is computed on gauss points with Gaussian quadratures?
===Use FEM Interpolation for magnetic permeability (true/false)?
It is set to true by default.
11. If the permeability is not defined analytically, set the magnetic permeability in each subdomains.
===Permeability in the conductive part (1:nb_dom_H)
12. Electrical conductivity in each subdomains.
===Conductivity in the conductive part (1:nb_dom_H)
13. The order of the polynomial function used to approximated the magnetic field.
===Type of finite element for magnetic field
It can be set to one or two.
14. Magnetic Reynolds number $$\Rm$$.
===Magnetic Reynolds number
15. Stabilization coefficient $$\beta_1$$, see the section Approximation of the Maxwell equations with H.
===Stabilization coefficient (divergence)
16. Stabilization coefficient $$\beta_3$$, see the section Approximation of the Maxwell equations with H.
===Stabilization coefficient for Dirichlet H and/or interface H/H
2. Information on the approximation of the scalar potential $$\phi$$ in the insulating domain.
1. Number of insulating subdomains where the scalar potential $$\phi$$ is used to approximate the Maxwell equations.
===Number of subdomains in magnetic potential (phi) mesh
It is set to zero by default. The following information are only read if it is set to true.
2. List of the insulating subdomains.
===List of subdomains for magnetic potential (phi) mesh
3. Number of boundary pieces with Dirichlet condition.
===How many boundary pieces for Dirichlet BCs on phi?
4. List of the boundary pieces with Dirichlet condition.
===List of boundary pieces for Dirichlet BCs on phi
5. Number of interfaces between the conducting and insulating subdomains.
===Number of interfaces between H and phi
6. List of the interface between the conducting and insulating subdomains.
===List of interfaces between H and phi
7. Permeability in the insulating domain. It does not depends of the insulating subdomains.
===Permeability in vacuum
8. The order of the polynomial function used to approximated the scalar potential.
===Type of finite element for scalar potential
It can be set to one or two. It needs to be larger than the one used for the magnetic field.
9. Stabilization coefficient $$\beta_2$$, see the section Approximation of the Maxwell equations with H.
===Stabilization coefficient (interface H/phi)
3. In addition, it is possible to use a quasi-static approximation.
===Quasi-static approximation (true) or (false)?
It is set to false by default. We refer to the section Fortran file condlim.f90 for more details on this set up.

## Information for the Maxwell equations solver

Set the following information on the solver for the Maxwell equations.

1. Maximum of iterations.
===Maximum number of iterations for Maxwell solver
2. Relative tolerance.
===Relative tolerance for Maxwell solver
3. Absolute tolerance.
===Absolute tolerance for Maxwell solver
4. Type of solver.
===Solver type for Maxwell (FGMRES, CG, ...)
It is possible to set it to GMRES (Generalized Minimal Residual method), FGMRES (Flexible Generalized Minimal Residual method) and CG (Conjugate Gradient method).
5. Type of preconditionner.
===Preconditionner type for Maxwell solver (HYPRE, JACOBI, MUMPS...)

# Setting for eigenvalue problem with Arpack

Eigenvalue problems for the Maxwell equations can be considered. The following parameters needs to be set.

1. Is Arpack used?
===Do we use Arpack?
It is set to false by default. The following information are only read if it is set to true.
2. Number of eigenvalues to compute.
===Number of eigenvalues to compute
3. Maximum number of Arpack iteration.
===Maximum number of Arpack iteration
4. Tolereance for Arpack solver.
===Tolerance for Arpack
5. Which eigen values are approximated (largest/smallest magnitude, real part or imaginary part).
===Which eigenvalues (''LM'', ''SM'', ''SR'', ''LR'' ''LI'', ''SI'')
6. Generation of visualization files for Paraview.
===Create 2D vtu files for Arpack? (true/false)
It is set to false by default.

# Output settings

Information on the outputs computed are provided as follows.

1. Frequency to write restart files of the variables approximated.
===Frequency to write restart file
This value is saved in inputs%freq_restart. The suite files for the Navier-Stokes variables have the following name suite_ns_Sxxx_Iyyy.mesh_name where:
1. xxx is the number of the subsection of the meridian plane (000, 001, etc.) associated to the restart file.
2. yyy is the time iteration divided by inputs%freq_restart when the file was generated.
3. mesh_name is the name of the mesh.
For the temperature, respectively the magnetic field, the nst is replaced by temp, respectively by maxwell.
2. Frequency to write the energies or other ouputs computed in the subroutine my_post_processing of the file main.f90
===Frequency to write energies
This value is saved in inputs%freq_en.
3. Frequency to generate visualization files for Paraview.
===Frequency to create plots
This value is saved in inputs%freq_plot
4. Number of planes used to generate the visualization file.
===Number of planes in real space for Visualization
It is set to ten by default.
5. It is possible to only do postprocessing of restarts files.
===Just postprocessing without computing? (true/false)

The section The subroutine my_post_processing details how to compute these outputs. Additional information can be computed by the code in the output file. These informations are written each inputs%freq_en time iterations.

1. Do the code checks the numerical stability?
===Check numerical stability (true/false)
The code check that the $$\bL^2$$-norm of the velocity field or the magnetic field is not larger than a hundred. This value can be changed in the file main.f90, look for inputs%check_numerical_stability.
2. Compute the average computational time per iteration.
===Verbose timing? (true/false)
3. Compute the divergence of the velocity field and the magnetic field.
===Verbose divergence? (true/false)
4. For problem involving the Navier-Stokes equations, the CFL can be computed.
===Verbose CFL? (true/false)

# Setting to force Fourier components of velocity field and magnetic field to zero

It is possible to set a list of Fourier components of all variables of the Navier-Stokes and Maxwell equations to zero. It is done as follows.

1. Are some Fourier modes set to zero?
===Should some modes be zeroed out?
The default value if false. The following information are only read if it is set to true.
2. Number of Fourier modes to set to zero for the Navier-Stokes equations approximations.
===How many Navier-Stokes modes to zero out?
3. List of above Fourier modes.
===List of Navier-Stokes modes to zero out?
4. Number of Fourier modes to set to zero for the Maxwell equations approximations.
===How Maxwell modes to zero out?
5. List of above Fourier modes.
===List of Maxwell modes to zero out?