Input file basics¶
Contents
Input file structure¶
Although this has been covered in the quickstart, we remind the reader that most input files have a similar structure regardless of which model (App) is being used.
On the whole, input files consist of four parts: the App dependencies, the Preamble, the App initialization, and the App run. So most input files look like
--------------------------------------------------------------------------------
-- App dependencies.
...
--------------------------------------------------------------------------------
-- Preamble.
...
--------------------------------------------------------------------------------
-- App initialization.
...
--------------------------------------------------------------------------------
-- App run.
...
We expand on the description of each part in the following sections:
App dependencies
This section loads the App one wishes to use for the simulation. At the moment these can be one of VlasovMaxwell, Gyrokinetic or Moments app:local Plasma = require("App.PlasmaOnCartGrid").VlasovMaxwell() -- Load the Vlasov App.
local Plasma = require("App.PlasmaOnCartGrid").Gyrokinetic() -- Load the Gyrokinetic App.
local Plasma = require("App.PlasmaOnCartGrid").Moments() -- Load the Moments App.
local Constants = require "Lib.Constants" -- Load universal physical Constants.
Preamble
In the Preamble one can declare local variables, functions and any object allowed by Lua which may help the user set up the calculation. Often this section is used to define user input parameters, calculate quantities derived from these inputs and create functions which we may later pass to the App. So for example, the simple Landau damping calculation in the first quickstart contained the following Preamble:permitt = 1.0 -- Permittivity of free space.
permeab = 1.0 -- Permeability of free space.
eV = 1.0 -- Elementary charge, or Joule-eV conversion factor.
elcMass = 1.0 -- Electron mass.
ionMass = 1.0 -- Ion mass.
nElc = 1.0 -- Electron number density.
nIon = nElc -- Ion number density.
Te = 1.0 -- Electron temperature.
Ti = Te -- Ion temperature.
vtElc = math.sqrt(eV*Te/elcMass) -- Electron thermal speed.
vtIon = math.sqrt(eV*Ti/ionMass) -- Ion thermal speed.
wpe = math.sqrt((eV^2)*nElc/(permitt*elcMass)) -- Plasma frequency.
lambdaD = vtElc/wpe -- Debye length.
-- Amplitude and wavenumber of sinusoidal perturbation.
pertA = 1.0e-3
pertK = .750/lambdaD
-- Maxwellian in (x,vx)-space, given the density (denU), bulk flow
-- velocity (flowU), mass and temperature (temp).
local function maxwellian1D(x, vx, den, flowU, mass, temp)
local v2 = (vx - flowU)^2
local vtSq = temp/mass
return (den/math.sqrt(2*math.pi*vtSq))*math.exp(-v2/(2*vtSq))
end
App initialization
After loading the App, and setting up the App preliminaries in the Preabmle, we must initialize the App itself. This is accomplished with a table likelocal plasmaApp = Plasma.App {
-----------------------------------------------------------------------------
-- Common.
...
-----------------------------------------------------------------------------
-- Species.
...
-----------------------------------------------------------------------------
-- Fields.
...
-----------------------------------------------------------------------------
-- ExternalFields.
...
-----------------------------------------------------------------------------
-- Extras.
...
}
- Common has parameters that are common to all Apps and control some aspects of the simulation, most notably the final simulation time and the frames to ouput.
- Species contains a declaration of each plasma species to be considered (e.g. electrons, hydrogen ions, neutrals).
- Fields specifies the electrostatic or electromagnetic fields to be included in the simulation.
- ExternalFields: Some simulations also require the specification of (possibly time-dependent) external fields. For gyrokinetics, parameters and functions pertaining to the magnetic geometry are specified here.
- Extras: there are additional features that some simulations may require.
App run
Gkyl input files conclude with a call to the run method of the App, in order to get the simulation running once the input file is called by the gkyl executable. This App run command looks likeplasmaApp:run()
The input file Common¶
As mentioned in the previous section, the App initialization has a section called the Common, which contains parameters common to all the Apps. Here we describe what these possible entries are and their default value (if a default value is not given it means that the user must provide this parameter).
Parameter |
Description |
Default |
---|---|---|
tEnd |
Final simulation time. |
|
lower |
Table with configuration space coordinates of lower boundaries. |
|
upper |
Table with configuration space coordinates of upper boundaries. |
|
cells |
Table with number of cells along configuration space each direction. |
|
nFrame |
Number of frames of data to write. Initial conditions are always written. For more fine-grained control over species and field output, see below. |
|
periodicDirs |
Periodic directions. Note: X is 1, Y is 2 and Z is 3. |
|
basis |
Basis functions to use. One of |
|
polyOrder |
Polynomial order of the basis. |
0 |
basis |
Basis functions to use. One of |
|
decompCuts |
For parallel simulations: Table with number of processors to use in each configuration space direction. |
|
useShared |
For parallel simulations: Set to |
|
maximumDt |
Largest time step size allowed. |
|
suggestedDt |
Initial suggested time-step. Adjusted as simulation progresses. |
|
cflFrac |
Fraction (usually 1.0) to multiply CFL determined time-step. |
1.0, or 2.0 for |
cfl |
CFL number to use in determining the time step. This parameter should be avoided and cflFrac used instead. |
|
timeStepper |
One of |
|
restartFrameEvery |
Frequency with which to write restart files, given as a decimal fraction. Default is every 5% (=0.05) of the simulation, or as frequently as frames are outputted (whichever is largest). |
|
calcIntQuantEvery |
Frequency with which to compute volume integrated quantities, given as a decimal fraction. |
Every time step. |
groupDiagnostics |
The default ( |
|
ioMethod |
Method to use for file output. One of |
|
logToFile |
If set to true, log messages are written to log file. |
|
Note
In general, you should not specify
cfl
orcflFrac
, unless either doing tests or explicitly controlling the time-step. The app will determine the time-step automatically.The
"rk3s4"
time-stepper allows taking twice the time-step as"rk2"
and"rk3"
at the cost of an additional RK stage. Hence, with this stepper a speed-up of 1.5X can be expected.(This feature may be superseeded soon) One can request additional parallelism in velocity space for kinetic simulations by setting
useShared = true
. This enables MPI shared memory. In this case thedecompCuts
must specify the number of nodes and not number of processors. That is, the total number of processors will be determined fromdecompCuts
and the number of threads per node.