Merge branch 'feature.emission.distribution' into 'master.dev'

[feature.emission.distribution] Added new particle emission SpaceIC "EmissionDistribution"

See merge request piclas/piclas!699

REGGIE.md

@@ -25,14 +25,15 @@ Overview of the test cases performed after a commit.
 
 Regression testing for PIC, solving the complete Maxwell equations with RK4: [Link to build](regressioncheck/CHE_PIC_maxwell_RK4/builds.ini).
 
-| **No.** |       **Case**       | **CMAKE-CONFIG** |                  **Feature**                   |        **Execution**         |          **Comparing**          |                                 **Readme**                                 |
-| :-----: | :------------------: | :--------------: | :--------------------------------------------: | :--------------------------: | :-----------------------------: | :------------------------------------------------------------------------: |
-|   01    |    2D_variable_B     |                  | external magnetic field from .h5 (equidistant) | nProcs=1,2,3,4,5,10,15,25,80 | PartAnalyze.csv, PIC-EMField.h5 |    [Link](regressioncheck/CHE_PIC_maxwell_RK4/2D_variable_B/readme.md)     |
-|   02    |    3D_variable_B     |                  | external magnetic field from .h5 (equidistant) | nProcs=1,2,3,4,5,10,15,25,32 | PartAnalyze.csv, PIC-EMField.h5 |    [Link](regressioncheck/CHE_PIC_maxwell_RK4/3D_variable_B/readme.md)     |
-|   03    | gyrotron_variable_Bz |                  |                  variable Bz                   |          nProcs=1,2          |     Database.csv, relative      | [Link](regressioncheck/CHE_PIC_maxwell_RK4/gyrotron_variable_Bz/readme.md) |
-|   04    |     IMD_coupling     |                  |           mapping from IMP to PICLas           |           nProcs=1           |         PartPata in Box         |     [Link](regressioncheck/CHE_PIC_maxwell_RK4/IMD_coupling/readme.md)     |
-|   05    |  initialIonization   |                  |                                                |           nProcs=2           |            PartPata             |  [Link](regressioncheck/CHE_PIC_maxwell_RK4/initialIonization/readme.md)   |
-|   06    | single_particle_PML  |                  |                      PML                       |           particle           |        nProcs=1,2,5,8,10        | [Link](regressioncheck/CHE_PIC_maxwell_RK4/single_particle_PML/readme.md)  |
+| **No.** |             **Case**            |                   **Feature**                  |         **Execution**        |          **Comparing**          |                                        **Readme**                                       |
+| :-----: |       :------------------:      | :--------------------------------------------: | :--------------------------: | :-----------------------------: | :-------------------------------------------------------------------------------------: |
+|    01   |          2D_variable_B          | external magnetic field from .h5 (equidistant) | nProcs=1,2,3,4,5,10,15,25,80 | PartAnalyze.csv, PIC-EMField.h5 |           [Link](regressioncheck/CHE_PIC_maxwell_RK4/2D_variable_B/readme.md)           |
+|    02   | 2D_variable_particle_init_n_T_v |   particle emission from a distribution in 2D  |         nProcs=1,2,5         |         PartAnalyze.csv         |  [Link](regressioncheck/CHE_PIC_maxwell_RK4/2D_variable_particle_init_n_T_v/readme.md)  |
+|    03   |          3D_variable_B          | external magnetic field from .h5 (equidistant) | nProcs=1,2,3,4,5,10,15,25,32 | PartAnalyze.csv, PIC-EMField.h5 |           [Link](regressioncheck/CHE_PIC_maxwell_RK4/3D_variable_B/readme.md)           |
+|    04   |       gyrotron_variable_Bz      |                   variable Bz                  |          nProcs=1,2          |      Database.csv, relative     |        [Link](regressioncheck/CHE_PIC_maxwell_RK4/gyrotron_variable_Bz/readme.md)       |
+|    05   |           IMD_coupling          |           mapping from IMP to PICLas           |           nProcs=1           |         PartPata in Box         |            [Link](regressioncheck/CHE_PIC_maxwell_RK4/IMD_coupling/readme.md)           |
+|    06   |        initialIonization        |                                                |           nProcs=2           |             PartPata            |         [Link](regressioncheck/CHE_PIC_maxwell_RK4/initialIonization/readme.md)         |
+|    06   |       single_particle_PML       |                       PML                      |           particle           |        nProcs=1,2,5,8,10        |        [Link](regressioncheck/CHE_PIC_maxwell_RK4/single_particle_PML/readme.md)        |
 
 #### CHE_DSMC
 

docs/documentation/userguide/features-and-models/particle-initialization-and-emission.md

@@ -74,7 +74,7 @@ Different `SpaceIC` are available and an overview is given in the table below.
 | photon_SEE_honeycomb |    Secondary electron emission through photon impact (honeycomb distribution)    | Section {ref}`sec:particle-photo-ionization` |
 |   photon_rectangle   |  Ionization of a background gas through photon impact (rectangular distribution) | Section {ref}`sec:particle-photo-ionization` |
 | photon_SEE_rectangle |   Secondary electron emission through photon impact (rectangular distribution)   | Section {ref}`sec:particle-photo-ionization` |
-|          WIP         |                               **WORK IN PROGRESS**                               |                                              |
+| EmissionDistribution |    Initial only ($t=0$) field-based ($n, T, v$) particle distribution from .h5   |  Section {ref}`sec:particle-emission-distri` |
 
 Common parameters required for most of the insertion routines are given below. The drift velocity is defined by the direction
 vector `VeloVecIC`, which is a unit vector, and a velocity magnitude [m/s]. The thermal velocity of particle is determined based
@@ -190,6 +190,71 @@ actual computational domain corresponds only to a quarter of the cylinder:
     Part-Species1-Init1-FirstQuadrantOnly       = T
     Part-Species1-Init2-FirstQuadrantOnly       = T
 
+(sec:particle-emission-distri)=
+### Emission Distribution
+To initialize a pre-defined distribution, e.g., from the output of a field-based or continuum-based solver, a particle distribution
+can be created from a .h5 file that contains $n, T, v_{r}$ and $v_{z}$ (particle number density, temperature and velocity in 2D
+cylindrical coordinates).
+This data needs to be supplied in a specific format and a different array for each species that is to be initialized in such a way
+is required.
+This emission option is selected via
+
+    ! Define the name of the data file
+    Part-EmissionDistributionFileName = reggie-linear-rot-symmetry-species-init.h5
+
+    ! OPTIONAL: Polynomial degree for particle emission in each element
+    Part-EmissionDistributionN = 1
+
+    ! For each species, the following information is required
+    Part-Species1-nInits   = 1
+    Part-Species1-Init1-SpaceIC                  = EmissionDistribution
+    Part-Species1-Init1-EmissionDistributionName = HeIon
+
+where `Part-EmissionDistributionFileName` defines the .h5 data file that contains the data, `Part-EmissionDistributionN` is an
+optional parameter for tuning the quality of the distribution within each element. It defines the polynomial degree for the
+particle emission in each element.
+The default value is 2(N+1) with N being the polynomial degree of the solution.
+The parameter `Part-Species1-Init1-SpaceIC` activates this specific emission type and `Part-Species1-Init1-EmissionDistributionName`
+is the name of the container in the .h5 file that yields the data for each species.
+
+An example setup is given in the regression check directory under
+[./regressioncheck/CHE_PIC_maxwell_RK4/2D_variable_particle_init_n_T_v](https://github.com/piclas-framework/piclas/tree/master/regressioncheck/CHE_PIC_maxwell_RK4/2D_variable_particle_init_n_T_v).
+The example uses 2D data defined in cylindrical coordinates for the velocity vector $v=v(r,z)$, which will be transformed to
+Cartesian coordinates in piclas.
+
+The .h5 file `reggie-linear-rot-symmetry-species-init.h5` contains the following information: **Attributes** that define the index
+of the coordinates and the properties
+
+    T   4
+    n   3
+    r   1
+    vr  5
+    vz  6
+    z   2
+
+and two **array** container, one for each species labelled `HeIon` and `electron` for singly charged Helium ions and electrons.
+These names must be used in the parameter input file.
+Each of these containers must provide the data in a $m \times n$ array and must be equidistant in each coordinate direction.
+The electron data begins with the following data
+
+    1.0   5.0     NaN      NaN        NaN        NaN
+    1.0   7.0  2.4E17  10000.0  1000000.0  1000000.0
+    1.0   9.0  2.4E17  10000.0  1000000.0  1000000.0
+    1.0  11.0  2.4E17  10000.0  1000000.0  1000000.0
+    1.0  13.0  2.4E17  10000.0  1000000.0  1000000.0
+    ...
+    ...
+
+and is allowed to contain NaN values, because the original data might be projected onto a equidistant Cartesian grid from a
+unstructured and non-rectangular mesh.
+These NaN values will automatically be replaced with zeros during read-in of the data.
+The original 2D data (equidistant mesh) must be unrolled into a 1D structure with one data point per row.
+As can be seen from the dataset above, the first column containing the $r$-coordinates is the outer loop and the $z$-coordinates in
+the second column represent the inner loop in this logic.
+Note that the temperature (translational, vibrational and electronic) of ions and atoms/molecules will be initialized with $300$ K.
+This will be changed in a future release. At the moment, only the electron temperature will be considered.
+
+
 ### Neutralization Boundaries (neutral outflow condition)
 There are different methods implemented to neutralize a charged particle flow, e.g., as encountered when simulation electric
 propulsion systems. Currently all methods require a specific geometry to function properly. For more details, see the regression

regressioncheck/CHE_PIC_maxwell_RK4/2D_variable_particle_init_n_T_v/PartAnalyze-ref.csv

@@ -0,0 +1,2 @@
+001-TIME,002-nPart-Spec-001,003-nPart-Spec-002,004-nPart-Spec-003,005-nPartIn-Spec-001,006-nPartIn-Spec-002,007-nPartIn-Spec-003,008-nPartOut-Spec-001,009-nPartOut-Spec-002,010-nPartOut-Spec-003,011-Ekin-001,012-Ekin-002,013-Ekin-003,014-EkinIn-001,015-EkinIn-002,016-EkinIn-003,017-EkinOut-001,018-EkinOut-002,019-EkinOut-003
+0.9999999999999999E-011,0.1364000000000000E+005,0.1365800000000000E+005,0.2729800000000000E+005,0.0000000000000000E+000,0.0000000000000000E+000,0.0000000000000000E+000,0.0000000000000000E+000,0.0000000000000000E+000,0.0000000000000000E+000,0.2935049538942454E-002,0.1650005540495363E-003,0.3100050092991994E-002,0.0000000000000000E+000,0.0000000000000000E+000,0.0000000000000000E+000,0.0000000000000000E+000,0.0000000000000000E+000,0.0000000000000000E+000

regressioncheck/CHE_PIC_maxwell_RK4/2D_variable_particle_init_n_T_v/analyze.ini

@@ -0,0 +1,5 @@
+! PartAnalyze.csv diff
+compare_data_file_name           = PartAnalyze.csv
+compare_data_file_reference      = PartAnalyze-ref.csv
+compare_data_file_tolerance      = 2e-2
+compare_data_file_tolerance_type = relative

regressioncheck/CHE_PIC_maxwell_RK4/2D_variable_particle_init_n_T_v/command_line.ini

@@ -0,0 +1 @@
+MPI=1,2,5

regressioncheck/CHE_PIC_maxwell_RK4/2D_variable_particle_init_n_T_v/hopr.ini

@@ -0,0 +1,43 @@
+!=============================================================================== !
+! MAKEFILE PARAMETER (put a "#" in front, NO blanks!)
+!=============================================================================== !
+! This is only a dummy parameter needed for the regression check
+#MPI=
+
+!=============================================================================== !
+! OUTPUT
+!=============================================================================== !
+  ProjectName   =2D-field-interpolation             ! name of the project (used for filenames)
+  Debugvisu     =F                           ! Write debug mesh to tecplot file
+  Logging       =F                           ! Write log files
+
+!=============================================================================== !
+! MESH
+!=============================================================================== !
+  Mode          =1                           ! 1 Cartesian 2 gambit file 3 CGNS 
+  nZones        =1                           ! number of zones
+  Corner        =(/0.,0.,0.,,  5.,0.,0.,,  5.,0.001,0.,,  0.,0.001,0. ,,  0.,0.,10.,,  5.,0.,10.,,  5.,0.001,10.,,  0.,0.001,10. /) ! [0,1]x[0,1]x[0,0.05]
+  nElems        =(/4,1,20/)                 ! Anzahl der Elemente in jede Richtung (nfine 4:15 5:32 5:54 7:128)
+  BCIndex       =(/1,1,1,1,1,1/)             ! Indices of UserDefinedBoundaries
+  elemtype      =108                         ! Elementform (108: Hexaeder)
+  useCurveds    =F                           ! T if curved boundaries defined
+  SpaceQuandt   =1.                          ! characteristic length of the mesh
+  ConformConnect=T
+
+!=============================================================================== !
+! BOUNDARY CONDITIONS
+!=============================================================================== !
+  nUserDefinedBoundaries=1
+    BoundaryName=BC_absorbing                  ! Outflow: open (absorbing)   [for MAXWELL]
+    BoundaryType=(/4,0,0,0/)                 ! Outflow: open (absorbing)   [for MAXWELL]
+
+!=============================================================================== !
+! BASIS
+!=============================================================================== !
+  NVisu         = 7
+
+!=============================================================================== !
+! SEARCH
+!=============================================================================== !
+!  nElemsNodeSearch=50
+!  RefineSideSearch=50

regressioncheck/CHE_PIC_maxwell_RK4/2D_variable_particle_init_n_T_v/parameter.ini

@@ -0,0 +1,116 @@
+! =============================================================================== !
+! EQUATION (linearscalaradvection)
+! =============================================================================== !
+IniExactFunc    = 0
+
+! =============================================================================== !
+! DISCRETIZATION
+! =============================================================================== !
+N               = 1  ! Polynomial degree
+NAnalyze        = 8 ! Number of analyze points
+
+! =============================================================================== !
+! MESH
+! =============================================================================== !
+MeshFile        = 2D-field-interpolation_mesh.h5
+useCurveds      = F
+! =============================================================================== !
+! OUTPUT / VISUALIZATION
+! =============================================================================== !
+ProjectName      = TE28_8
+Logging          = F
+WriteErrorFiles  = F
+printRandomSeeds = F
+DoCalcErrorNorms = F
+TrackingMethod   = refmapping!,tracing,triatracking
+
+!CheckExchangeProcs = F ! deactivate the asymmetric communicator check
+! =============================================================================== !
+! CALCULATION
+! =============================================================================== !
+!Part-DelayTime = 1.0
+PIC-DoDeposition = F
+
+tend       = 1.0E-11
+Analyze_dt = 1.0E-11
+CFLscale   = 0.9     ! Scaling of theoretical CFL number
+c_corr     = 1
+
+CalcMeshInfo=T
+CalcHaloInfo=T
+CalcEMFieldOutput=T
+!Particles-HaloEpsVelo=1e9
+CalcElectronIonDensity=T
+CalcElectronTemperature=T
+
+! =============================================================================== !
+! Load Balance
+! =============================================================================== !
+DoLoadBalance           = T
+DoInitialAutoRestart    = T
+Load-DeviationThreshold = 1e-9
+LoadBalanceMaxSteps     = 2
+Particles-MPIWeight     = 0.01
+
+! =============================================================================== !
+! PARTICLES
+! =============================================================================== !
+Part-maxParticleNumber    = 150000
+Part-nSpecies             = 2
+Part-nBounds              = 1
+Part-Boundary1-SourceName = BC_absorbing
+Part-Boundary1-Condition  = reflective
+
+PIC-Interpolation-Type    = particle_position
+
+PIC-Deposition-Type         = shape_function
+PIC-shapefunction-radius    = 0.85
+PIC-shapefunction-dimension = 2
+PIC-shapefunction-direction = 2
+PIC-shapefunction-alpha     = 4
+
+Part-FIBGMdeltas          = (/0.5,0.001,.5/)
+
+Part-EmissionDistributionFileName = reggie-linear-rot-symmetry-species-init.h5
+
+! =============================================================================== !
+! Species1 - electrons
+! =============================================================================== !
+Part-Species1-ChargeIC              = -1.60217653E-19
+Part-Species1-MassIC                = 9.1093826E-31
+Part-Species1-MacroParticleFactor   = 2E11
+
+Part-Species1-nInits = 1
+
+Part-Species1-Init1-SpaceIC                  = EmissionDistribution
+Part-Species1-Init1-EmissionDistributionName = electron
+
+! =============================================================================== !
+! Species2 | HeIon
+! =============================================================================== !
+Part-Species2-ChargeIC = 1.60217653E-19
+Part-Species2-MassIC   = 6.645565470903E-027
+Part-Species2-MacroParticleFactor   = 2E11
+
+Part-Species2-nInits   = 1
+
+Part-Species2-Init1-SpaceIC                  = EmissionDistribution
+Part-Species2-Init1-EmissionDistributionName = HeIon
+
+
+! =============================================================================== !
+! Analysis
+! =============================================================================== !
+Part-AnalyzeStep         = 1
+CalcKineticEnergy        = T
+CalcPartBalance          = T
+CalcCharge               = F
+CalcPotentialEnergy      = T
+CalcNumSpec              = T
+Part-NumberOfRandomSeeds = 2
+Particles-RandomSeed1    = 1180520427
+Particles-RandomSeed2    = 1708457652
+PIC-OutputSource         = T ! HDF5 output of maxwell source terms
+PIC-VerifyCharge         = F
+NVisu=4
+VisuParticles=T

regressioncheck/CHE_PIC_maxwell_RK4/2D_variable_particle_init_n_T_v/readme.md

@@ -0,0 +1,4 @@
+# 2D Variable Emission Distribution
+- Read particle emission initialization info from reggie-linear-rot-symmetry-species-init.h5
+  - n, T, vx, vy, vz for different species
+  - Transformation to Cartesian coordinates from cylinder coordinates due to the velocity being defined by the function v=v(r,z)

regressioncheck/NIG_maxwell_RK4/CoaxialCable_DMD/externals.ini

@@ -1,9 +1,9 @@
 ! --- Externals Tool Reggie
-MPI               =  1                                ! Single execution
-externalbinary    =  ./bin/dmd                        ! Relative binary path in build directory
-externaldirectory =  post-dmd                         ! Directory name, where the files are located for the external tool reggie
-externalruntime   =  post                             ! Run after piclas is completed (post: after, pre: before)
-cmd_suffix        =  ../coaxial_State_000.00000*.h5   ! Suffix for the binary execution
-!cmd_pre_execute   =  pwd\s>\stest.txt                ! "\s" resembles a white space character in the command (simply using " " is not allowed)
+MPI               =  1                              ,  1                                 ! Single execution
+externalbinary    =  ./bin/dmd                      ,  ./bin/piclas2vtk                  ! Relative binary path in build directory
+externaldirectory =  post-dmd                       ,  post-VTK-conversion               ! Directory name, where the files are located for the external tool reggie
+externalruntime   =  post                           ,  post                              ! Run after piclas is completed (post: after, pre: before)
+cmd_suffix        =  ../coaxial_State_000.00000*.h5 ,  ../post-dmd/coaxial_DMD.h5        ! Suffix for the binary execution
+cmd_pre_execute   =  ls                             ,  ln\s-sf\s../cylinderNgeo2_mesh.h5 ! "\s" resembles a white space character in the command (simply using " " is not allowed)
 
-!nocrosscombination:MPI,externalbinary,externaldirectory,externalruntime,cmd_suffix,cmd_pre_execute
+nocrosscombination:MPI,externalbinary,externaldirectory,externalruntime,cmd_suffix,cmd_pre_execute

regressioncheck/NIG_maxwell_RK4/CoaxialCable_DMD/post-VTK-conversion/parameter.ini

@@ -0,0 +1,2 @@
+NVisu = 1
+!VisuParticles = T