Merge branch 'feature.backGroundGas.regions' into 'master.dev'

Definition of background gas regions & treatment of relativistic electron energies in MCC

See merge request piclas/piclas!634

docs/documentation/userguide/features-and-models/BGG.md

@@ -18,26 +18,54 @@ initialization regions are allowed if the species is already defined a backgroun
     Part-Species1-PartDensity = 1E+22
 
 Other species parameters such as mass, charge, temperature and velocity distribution for the background are also defined by the
-regular read-in parameters. Every time step particles are generated from the background gas (for a mixture, the species of the generated particle is chosen
+regular read-in parameters. A mixture as a background gas can be simulated by simply defining multiple background species. Every
+time step particles are generated from the background gas (for a mixture, the species of the generated particle is chosen
 based on the species composition) and paired with the particle species. Subsequently, the collision probabilities are calculated
 using the conventional DSMC routines and the VHS cross-section model. Afterwards, the collision process is performed (if the
 probability is greater than a random number) and it is tested whether additional energy exchange and chemical reactions occur.
 While the VHS model is sufficient to model collisions between neutral species, it cannot reproduce the phenomena of a
 neutral-electron interaction. For this purpose, the cross-section based collision probabilities should be utilized, which are
 discussed in the following section.
 
-A spatially varying background gas distribution may be used by running a pure DSMC simulation beforehand and using a time-averaged
+## Distribution from DSMC result
+
+A spatially varying background gas distribution may be used by running a stand-alone DSMC simulation beforehand and using a time-averaged
 DSMC state file (*PROJECT_DSMCState_\*.h5*) as input for the actual simulation by setting
 
     Particles-BGGas-UseDistribution              = T
     Particles-MacroscopicRestart-Filename        = DSMCResult.h5
-    Part-SpeciesX-InitX-DistributionSpeciesIndex = 1
+    Part-SpeciesX-InitX-BGG-Distribution-SpeciesIndex = 1
 
 where the first parameter activates the background gas distribution and the second parameter supplies the relative path to the file
 from which the background gas density, velocity and temperature field is read (cell-constant values).
 The third parameter defines which species index within the DSMC file is to be used as it may contain multiple species.
 
-A mixture as a background gas can be simulated by simply defining multiple background species. If the number densities of the background gas species differ greatly and a specific background species is of interest (or the interaction with it) that has a lower number density compared to the other background species, it can be defined as a so-called trace species as shown below.
+## Regions
+
+Another possibility to define a non-constant background gas is available through the definition of regions. Multiple regions defined
+by simple geometrical volumes (e.g. cylinder) can be mapped to different species. First, one or more regions are defined:
+
+    Particles-BGGas-nRegions                  = 1
+    Particles-BGGas-Region1-Type              = cylinder
+    Particles-BGGas-Region1-RadiusIC          = 5E-6
+    Particles-BGGas-Region1-CylinderHeightIC  = 5E-6
+    Particles-BGGas-Region1-BasePointIC       = (/0.,0.,0./)
+    Particles-BGGas-Region1-BaseVector1IC     = (/1.,0.,0./)
+    Particles-BGGas-Region1-BaseVector2IC     = (/0.,1.,0./)
+
+Here, a cylinder is defined by two base vectors (from which a normal is determined for the direction of the cylinder height),
+basepoint, radius and cylinder height. The definition of the species is the same as described above, with the addition of an
+additional parameter, defining in which region, these properties should be applied to:
+
+    Part-Species1-Init1-BGG-Region            = 1
+
+While a species can be part of different regions through multiple inits and multiple species can be part of a single region,
+overlapping regions are not allowed. Whether an element is within a region is determined through the midpoint of the element and
+thus it does not have to be fully enveloped.
+
+## Trace species
+
+If the number densities of the background gas species differ greatly and a specific background species is of interest (or the interaction with it) that has a lower number density compared to the other background species, it can be defined as a so-called trace species as shown below.
 
     Part-vMPF                        = T
     Part-Species1-Init1-TraceSpecies = T

regressioncheck/CHE_DSMC/BackgroundGas_RegionsDefinition/DSMC.ini

@@ -0,0 +1,27 @@
+! =============================================================================== !
+! Species1, N2
+! =============================================================================== !
+Part-Species1-SpeciesName       = N2
+Part-Species1-InteractionID     = 2
+Part-Species1-Tref              = 273
+Part-Species1-dref              = 4.17E-10
+Part-Species1-omega             = 0.24
+Part-Species1-CharaTempVib      = 3393.3
+Part-Species1-Ediss_eV          = 9.79
+! =============================================================================== !
+! Species1, He
+! =============================================================================== !
+Part-Species2-SpeciesName       = He
+Part-Species2-InteractionID     = 1
+Part-Species2-Tref              = 273
+Part-Species2-dref              = 2.287E-10
+Part-Species2-omega             = 0.147
+Part-Species2-HeatOfFormation_K = 0.0
+! =============================================================================== !
+! Species3, e
+! =============================================================================== !
+Part-Species3-SpeciesName       = electron
+Part-Species3-InteractionID     = 4
+Part-Species3-Tref              = 273
+Part-Species3-dref              = 1E-15
+Part-Species3-omega             = 0.147

regressioncheck/CHE_DSMC/BackgroundGas_RegionsDefinition/analyze.ini

@@ -0,0 +1,6 @@
+! Compare cell-local values
+h5diff_file            = BGG_Regions_DSMCState_000.00000000002000000.h5
+h5diff_reference_file  = BGG_Regions_DSMCState_000.00000000002000000_ref.h5
+h5diff_data_set        = ElemData
+h5diff_tolerance_value = 5E-2
+h5diff_tolerance_type  = relative

regressioncheck/CHE_DSMC/BackgroundGas_RegionsDefinition/command_line.ini

@@ -0,0 +1,2 @@
+MPI=1,6
+cmd_suffix=DSMC.ini

regressioncheck/CHE_DSMC/BackgroundGas_RegionsDefinition/hopr.ini

@@ -0,0 +1,39 @@
+ProjectName  = cube
+Debugvisu    = T
+DebugVisuLevel=2
+NVisu        =1
+Mode         =1
+
+DEFVAR = (REAL):   minus_x = -0.5
+DEFVAR = (REAL):   plus_x = 0.5
+
+DEFVAR = (REAL):   minus_y = -0.5
+DEFVAR = (REAL):   plus_y = 0.5
+
+DEFVAR = (REAL):   minus_z = 0.0
+DEFVAR = (REAL):   plus_z = 10.0
+
+Corner   =(/minus_x,minus_y,minus_z ,, plus_x,minus_y,minus_z ,, plus_x,plus_y,minus_z ,, minus_x,plus_y,minus_z ,, minus_x,minus_y,plus_z ,, plus_x,minus_y,plus_z ,, plus_x,plus_y,plus_z ,, minus_x,plus_y,plus_z /)
+nElems   =(/4,4,4/)
+elemtype =108
+
+BCIndex  =(/6 ,4 ,1 ,3 ,2 ,5/)
+!        =(/z-,y-,x+,y+,x-,z+/)
+nZones = 1
+nUserDefinedBoundaries=6
+BoundaryName=BC_Xplus
+BoundaryType=(/4,0,0,0/)
+BoundaryName=BC_Xminus
+BoundaryType=(/4,0,0,0/)
+BoundaryName=BC_Yplus
+BoundaryType=(/4,0,0,0/)
+BoundaryName=BC_Yminus
+BoundaryType=(/4,0,0,0/)
+BoundaryName=BC_Zplus
+BoundaryType=(/4,0,0,0/)
+BoundaryName=BC_Zminus
+BoundaryType=(/4,0,0,0/)
+
+postscalemesh=true
+meshscale=1e-3
+jacobiantolerance=1e-20

regressioncheck/CHE_DSMC/BackgroundGas_RegionsDefinition/parameter.ini

@@ -0,0 +1,159 @@
+
+IniExactFunc = 0
+N = 1
+NVisu = 1
+! =============================================================================== !
+! CALCULATION
+! =============================================================================== !
+tend                     = 2E-11
+Analyze_dt               = 2E-11
+ManualTimeStep           = 1E-11
+! Volume-average
+Part-WriteMacroValues = T
+Part-IterationForMacroVal = 2
+! time output
+Part-AnalyzeStep        = 1
+IterDisplayStep         = 1
+! =============================================================================== !
+! LOAD BALANCE
+! =============================================================================== !
+Particles-MPIWeight   = 1000
+Particles-HaloEpsVelo = 1e3
+DoLoadBalance         = T
+PartWeightLoadBalance = T
+! Initial load balance
+DoInitialAutoRestart  = T
+InitialAutoRestart-PartWeightLoadBalance = T
+LoadBalanceMaxSteps   = 1
+Load-DeviationThreshold = 1E-9
+! =============================================================================== !
+! MESH
+! =============================================================================== !
+MeshFile      = cube_mesh.h5
+useCurveds    = F
+TrackingMethod = triatracking
+! =============================================================================== !
+! OUTPUT / VISUALIZATION
+! =============================================================================== !
+ProjectName     = BGG_Regions
+Logging         = F
+WriteErrorFiles = F
+printRandomSeeds= F
+printMPINeighborWarnings=F
+! =============================================================================== !
+! DSMC
+! =============================================================================== !
+UseDSMC                           = T
+Particles-DSMC-CollisMode         = 2
+Part-NumberOfRandomSeeds          = 2
+Particles-RandomSeed1             = 1
+Particles-RandomSeed2             = 2
+Particles-DSMC-RotRelaxProb       = 0.2
+Particles-DSMC-VibRelaxProb       = 0.05
+Particles-DSMC-CalcQualityFactors = T
+
+! Collision cross-section
+Particles-CollXSec-Database       = MCC_Database.h5
+Part-Species3-UseCollXSec         = F,T
+! =============================================================================== !
+! PARTICLES
+! =============================================================================== !
+Part-maxParticleNumber    = 500000
+! Boundaries
+Part-nBounds=6
+Part-Boundary1-SourceName=BC_Xplus
+Part-Boundary1-Condition=reflective
+Part-Boundary2-SourceName=BC_Xminus
+Part-Boundary2-Condition=reflective
+Part-Boundary3-SourceName=BC_Yplus
+Part-Boundary3-Condition=reflective
+Part-Boundary4-SourceName=BC_Yminus
+Part-Boundary4-Condition=reflective
+Part-Boundary5-SourceName=BC_Zplus
+Part-Boundary5-Condition=reflective
+Part-Boundary6-SourceName=BC_Zminus
+Part-Boundary6-Condition=reflective
+Part-FIBGMdeltas          = (/1E-3,1E-3,1E-2/)
+Part-FactorFIBGM          = (/ 4.0, 4.0, 40.0 /)
+! =============================================================================== !
+! Background Gas Regions
+! =============================================================================== !
+Particles-BGGas-nRegions                  = 3
+
+Particles-BGGas-Region1-Type              = cylinder
+Particles-BGGas-Region1-RadiusIC          = 0.0005
+Particles-BGGas-Region1-CylinderHeightIC  = 0.0025
+Particles-BGGas-Region1-BasePointIC       = (/0.,0.,0./)
+Particles-BGGas-Region1-BaseVector1IC     = (/1.,0.,0./)
+Particles-BGGas-Region1-BaseVector2IC     = (/0.,1.,0./)
+
+Particles-BGGas-Region2-Type              = cylinder
+Particles-BGGas-Region2-RadiusIC          = 0.0005
+Particles-BGGas-Region2-CylinderHeightIC  = 0.0025
+Particles-BGGas-Region2-BasePointIC       = (/0.,0.,0.0025/)
+Particles-BGGas-Region2-BaseVector1IC     = (/1.,0.,0./)
+Particles-BGGas-Region2-BaseVector2IC     = (/0.,1.,0./)
+
+Particles-BGGas-Region3-Type              = cylinder
+Particles-BGGas-Region3-RadiusIC          = 0.0005
+Particles-BGGas-Region3-CylinderHeightIC  = 0.0025
+Particles-BGGas-Region3-BasePointIC       = (/0.,0.,0.005/)
+Particles-BGGas-Region3-BaseVector1IC     = (/1.,0.,0./)
+Particles-BGGas-Region3-BaseVector2IC     = (/0.,1.,0./)
+! =============================================================================== !
+Part-nSpecies                = 3
+Part-Species$-MacroParticleFactor     = 1E6
+! =============================================================================== !
+! Species1 | N2
+! =============================================================================== !
+Part-Species1-MassIC                  = 4.65200E-26    ! N2 Molecular Mass
+Part-Species1-ChargeIC                = 0
+
+Part-Species1-nInits = 2
+Part-Species1-Init1-SpaceIC                 = background
+Part-Species1-Init1-BGG-Region              = 1
+Part-Species1-Init1-velocityDistribution    = maxwell_lpn
+Part-Species1-Init1-MWTemperatureIC         = 1000.0
+Part-Species1-Init1-PartDensity             = 1E23
+Part-Species1-Init1-VeloIC                  = 500.
+Part-Species1-Init1-VeloVecIC               = (/0.,0.,1./)
+Part-Species1-Init1-TempVib                 = 1000.0
+Part-Species1-Init1-TempRot                 = 2000.0
+
+Part-Species1-Init2-SpaceIC                 = background
+Part-Species1-Init2-BGG-Region              = 3
+Part-Species1-Init2-velocityDistribution    = maxwell_lpn
+Part-Species1-Init2-MWTemperatureIC         = 5000.0
+Part-Species1-Init2-PartDensity             = 5E24
+Part-Species1-Init2-VeloIC                  = 0
+Part-Species1-Init2-VeloVecIC               = (/0.,0.,1./)
+Part-Species1-Init2-TempVib                 = 3000.0
+Part-Species1-Init2-TempRot                 = 4000.0
+! =============================================================================== !
+! Species2 | He
+! =============================================================================== !
+Part-Species2-MassIC                        = 6.6464764E-27
+Part-Species2-ChargeIC                      = 0
+
+Part-Species2-nInits = 2
+Part-Species2-Init1-SpaceIC                 = background
+Part-Species2-Init1-BGG-Region              = 2
+Part-Species2-Init1-velocityDistribution    = maxwell_lpn
+Part-Species2-Init1-MWTemperatureIC         = 1500.0
+Part-Species2-Init1-PartDensity             = 1E24
+Part-Species2-Init1-VeloIC                  = 250
+Part-Species2-Init1-VeloVecIC               = (/1.,0.,0./)
+
+Part-Species2-Init2-SpaceIC                 = background
+Part-Species2-Init2-BGG-Region              = 3
+Part-Species2-Init2-velocityDistribution    = maxwell_lpn
+Part-Species2-Init2-MWTemperatureIC         = 2500.0
+Part-Species2-Init2-PartDensity             = 5E24
+Part-Species2-Init2-VeloIC                  = 750
+Part-Species2-Init2-VeloVecIC               = (/0.,1.,0./)
+
+! =============================================================================== !
+! Species3 | electron
+! =============================================================================== !
+Part-Species3-MassIC                  = 6.6464764E-27
+Part-Species3-ChargeIC                = 0

regressioncheck/CHE_DSMC/BackgroundGas_RegionsDefinition/readme.md

@@ -0,0 +1,7 @@
+# Background gas using regions
+* Reservoir with 3 species and 3 background gas regions
+  * 1 region with N2 (1E23/m3), 1 region with He (1E24/m3) and 1 region with N2/He (1E25/m3 in total)
+* Corresponding number density and temparte is verified with DSMCState output in the respective species container
+  * Compared as part of the regression test
+* Interaction with particle species was verified by the collision probability
+  * Comparison with DSMCState not possible due to strong fluctuations, third species is not inserted

regressioncheck/CHE_DSMC/BackgroundGas_VHS_MCC/analyze.ini

@@ -1,6 +1,6 @@
 ! compare the PartAnalyze.csv with a reference file
-compare_data_file_name      = PartAnalyze.csv, PartAnalyze.csv, PartAnalyze.csv
-compare_data_file_reference = PartAnalyze_ref_VHS.csv, PartAnalyze_ref_MCC.csv, PartAnalyze_ref_MCC.csv
+compare_data_file_name      = PartAnalyze.csv, PartAnalyze.csv, PartAnalyze.csv, PartAnalyze.csv, PartAnalyze.csv, PartAnalyze.csv
+compare_data_file_reference = PartAnalyze_ref_VHS.csv, PartAnalyze_ref_MCC.csv, PartAnalyze_ref_MCC.csv, PartAnalyze_ref_VHS.csv, PartAnalyze_ref_MCC.csv, PartAnalyze_ref_MCC.csv
 compare_data_file_tolerance = 6e-2
 compare_data_file_tolerance_type = relative
 ! Allowing difference in values: Electronic excitation and thus the degree of freedom can fluctuate strongly

regressioncheck/CHE_DSMC/BackgroundGas_VHS_MCC/excludeBuild.ini

@@ -0,0 +1,2 @@
+! Skip N=1 hard coded
+PICLAS_POLYNOMIAL_DEGREE=1

regressioncheck/CHE_DSMC/BackgroundGas_VHS_MCC/parameter.ini

@@ -65,16 +65,27 @@ Part-maxParticleNumber      = 500000
 Part-nSpecies               = 3
 ! Collision cross-section
 Particles-CollXSec-Database       = MCC_Database.h5
-Particles-CollXSec-NullCollision  = F,F,T
-Part-Species2-UseCollXSec         = F,T,T
-nocrosscombination:Particles-CollXSec-NullCollision,Part-Species2-UseCollXSec
+Particles-CollXSec-NullCollision  = F,F,T,F,F,T
+Part-Species2-UseCollXSec         = F,T,T,F,T,T
+nocrosscombination:Particles-CollXSec-NullCollision,Part-Species2-UseCollXSec,Particles-BGGas-nRegions
+
+Particles-BGGas-nRegions                  = 0,0,0,1,1,1
+
+Particles-BGGas-Region1-Type              = cylinder
+Particles-BGGas-Region1-RadiusIC          = 5E-6
+Particles-BGGas-Region1-CylinderHeightIC  = 5E-6
+Particles-BGGas-Region1-BasePointIC       = (/0.,0.,0./)
+Particles-BGGas-Region1-BaseVector1IC     = (/1.,0.,0./)
+Particles-BGGas-Region1-BaseVector2IC     = (/0.,1.,0./)
 ! =============================================================================== !
 ! Species1 | He Atom
 ! =============================================================================== !
 Part-Species1-MassIC                      = 6.6464764E-27
 Part-Species1-ChargeIC                    = 0
 Part-Species1-nInits=1
 Part-Species1-Init1-SpaceIC               = background
+Part-Species1-Init1-BGG-Region            = 1
+
 Part-Species1-Init1-PartDensity           = 1E+22
 Part-Species1-Init1-velocityDistribution  = maxwell_lpn
 Part-Species1-Init1-MWTemperatureIC       = 300

regressioncheck/NIG_PIC_poisson_Boris-Leapfrog/2D_HET_Liu2010/parameter.ini

@@ -204,7 +204,7 @@ Part-Species1-nInits   = 1
 
 Part-Species1-Init1-SpaceIC                  = background
 Part-Species1-Init1-velocityDistribution     = maxwell_lpn
-Part-Species1-Init1-DistributionSpeciesIndex = 1 !index of species in the DSMCState file
+Part-Species1-Init1-BGG-Distribution-SpeciesIndex = 1 !index of species in the DSMCState file
 Particles-BGGas-UseDistribution              = T
 Particles-MacroscopicRestart-Filename        = pre-BGGas/2D_HET_Liu2010_DSMCState_000.0007000000.h5
 

regressioncheck/NIG_PIC_poisson_Boris-Leapfrog/3D_HET_Liu2010/parameter.ini

@@ -210,7 +210,7 @@ Part-Species1-nInits   = 1
 
 Part-Species1-Init1-SpaceIC                  = background
 Part-Species1-Init1-velocityDistribution     = maxwell_lpn
-Part-Species1-Init1-DistributionSpeciesIndex = 1 !index of species in the DSMCState file
+Part-Species1-Init1-BGG-Distribution-SpeciesIndex = 1 !index of species in the DSMCState file
 Particles-BGGas-UseDistribution              = T
 Particles-MacroscopicRestart-Filename        = neutral-DSMC/3D_HET_Liu2010_DSMCState_000.00100000000000000.h5