How to control NUM from UI

A first way of controlling the execution of SPIS/NUM solvers is through the source code. The object oriented (OO) language Java allows an easy handling of objects like a Spacecraft, a Plasma or a VolumeDistribution. In practice, this can be done either:

- directly in the NUM Java source code as documented in Java for NUM.html (Java basics), NUM architecture.html (code architecture) and NUM integration in framework.html (practical file integration)

- through the Jython command line of SPIS/UI (still to be documented)

The second simplified way of controlling the execution of SPIS/NUM is through a more classical user interface, offering the capability to modify parameters, either global or local. This is the subject of this page. Of course it reduces somewhat the range of possibilities with respect to what is really supported by the solvers.

The advanced users may look at the source code of ..\API\public\spis\Top\Simulation\SimulationFromUIParams.html, or sometimes other routines, to see how the global parameters control the simulation at top level. A practical way to find what a global parameter is used for, is to search where is extracted, which can easily be done by looking where the String variable containing its name is used. All these static Strings are defined in the Common class (and a global parameter name should always be taken from these common variables, never hard-coded anywhere in the code).

Global parameters are presented first, local parameters, i.e. fields living either in the volume or on a surface (spacecraft or external boundary), are presented next.

Note the last column of the tables below, stating whether each property is in use or not as of this software version (currently 4.0).

As explained in UI documentation, local parameters are based on Material/Electric/Plasma properties that can be edited via GUI, and are then to be assigned locally on your CAD model group per group thanks to UI Group Editor. Global parameters are simply edited in UI Global Parameter Editor.

Warnings

From last SPIS version 4.0, some changes of the RC4.3 version need a particular attention from the user:

- The definition of the initial simulation time step is generally required in order to limit the initial time step.

- Multiple sources are possible on a single surface.

- Correct display of neutral densities and currents both for sources or environment. The unit of the local parameter source current is common to all sources.

- External boundary condition with no injection of particles and particle reflection

- Electric field monitoring

- Particle trajectory monitoring

- Extension of material list and material parameter list

- Limitation of the secondary emission due to grazing incidence electrons (theta max = 60°)

- User defined integration duration for the plasma and the populations, see Time_steps_RC_4.3.

- Monitoring of the current density vectors map and mean kinetic energy map

- Multiple volume interactions during a single simulation (only CEX reaction available as of today)

- Plasma neutrality: imposing neutrality instead of solving Poisson equation

- Possibility to compute the electric field with vacuum hypothesis: Laplace equation instead of Poisson equation, setting space charge to zero.

Global parameters

The general behaviour of NUM solvers is ruled by global parameters. They are organised by section:

- Simulation control

- Plasma

- MultiZone

- Poisson equation

- B Field

- Spacecraft

- Particles sources on spacecraft

- Surface interactions

- Volume interactions

- Outputs

- Scenario

In each section the parameters are first reviewed, then listed in a table.

They can be edited through a spreadsheet editor, which is launched by the Solvers/SPIS-NUM/ Global Param menu, or through the spreadsheet-like button click.

Simulation control

The hierarchical structure of a simulation is outlined in the figure below. The nested boxes reflect the object structure of the code (what the basic user user may not care about) while the arrows represent the time evolution of a simulation (what he needs to be aware of).

The largest allowable time steps at each nested level are written in red. They are controlled by user defined parameters:

- At particle population level (noted thisPopDt): in the past the maximum allowable time steps was to be defined so that particles do not cross more than a fraction of a cell at each times step (CFL-like condition). These maximum time steps are defined below in sections plasma / particle sources / interactions respectively for ambient particles, actively emitted particles and secondary particles (parameters xxxxDt). They can either be user-defined (best if user can do that!) or automatically determined by the code (default). The user must be warned that the code automated time step determination is rather coarse as it is based on the particle steps at injection. If particles are strongly accelerated after injection, time step can get too coarse and result in inaccuracies in trajectory integration (define them manually in such cases). However today, the improved trajectory integration scheme (see PIC model) suppresses this constraint. The integration is either exact (parabolic trajectories), or with an adaptive time step (subcycling) with controlled accuracy (Runge-Kutta Cash-Karp method, since SPIS v4.0).

- At plasma level (noted plasmaDt): here the maximum authorised time step plasmaDt should be smaller than a plasma period (~1/w_p). In principle if matter populations are sped up (see numerical times below), the allowed plasmaDt is increased by the same factor (since the numerical integration time of these populations is reduced by that factor). If plasmaDt is set to 0, it is determined semi automatically: the lower level time step (smallest time step allowed among matter populations) is used, which is a degraded criterion compared to the plasma period (however for cells larger than Debye length, the CFL condition for particles is stronger than this plasma stability criterion, hence this semi-automatic setting is sufficient for stability, even though not optimal).

- At simulation level (noted simulationDt): the top level time step simulationDt is constrained by the stability of the SC-plasma coupling (for a floating SC). The smaller the SC capacitances, the faster the SC dynamics, the smaller this time step must be. Theoretical limits are simulationDt << Capacitance ´ Potential / CollectedCurrent (at eigenvalue level for local values). In practice SC absolute capacitance C_sat is the smallest capacitance and yields the largest eigenvalue, hence the stability criterion is often simulationDt << C_sat ´ spacecraftPotential / totalCollectedCurrent. If the exact time evolution of the SC absolute potential is not of major concern to the user (if equilibrium only is pursued) the value of C_sat can thus be overestimated to improve stability and/or maximum allowed simulationDt (C_sat becomes a parameter of numerical convergence to steady state). If simulationDt is set to 0, it is determined semi automatically: the lower level time step (plasmaDt) is used, which is a degraded criterion compared to the CU/I eigenvalue criterion (but usually stronger, hence insuring stability)

Since SPIS v4.0 an extra constraint applies to the maximum allowable time scale, the validity of dV. As explained in the circuit solver technical note, in the new implicit solver, current change estimations are supplied to the circuit solver with a given validity range for potential changes. On the other hand some of the above constraints can be relaxed with this new feature, in particular the one on simulationDt which is in a way taken into account automatically by the solver.

Combined with the automatic determination of the times step of the new circuit solver (cf. simulationDt parameter), much faster convergence can often by achieved.

At each level involving different time structures, if ever one of the characteristic times is faster than the others it may be sped up by considering that the fast process dynamics is quasi-static as compared to the slow one. In such a case (to be assessed by the user), the dynamics of the slower process may not need to be modelled during as long a duration as the fast one, simply because it reached its steady state in a smaller amount of time. Among the main three nested levels of the chart (Simulation, Plasma, Matter), this method, that we may call numerical times, can be used at the two lower levels:

- at matter level: computation of faster populations dynamics (typically electrons or sometimes fast ions) can be sped up by only integrating over a smaller time for these populations than for the others. This is controlled by one parameter per population (see below in sections plasma / particle sources / interactions respectively for ambient particles, actively emitted particles and secondary particles). It is the responsibility of the user to control the validity of the quasi-steadiness assumption. These parameters called xxxxSpeedUp are by default set to 1 (no speed up).

- at plasma-SC level: plasma dynamics is often faster than spacecraft charging (at least differential charging). Plasma can thus often be considered as stationary at the large time scale of surface potential dynamics (to be checked by user in each case). If so, plasma dynamics can be sped up thanks to the plasmaSpeedUp parameter in the table below. At each step of the SC-plasma loop (blue boxes) the integration duration of plasma (N x plasmaDt) is reduced compared to the SC integration duration (scDt) by a factor plasmaSpeedUp.

NB: in some modelling cases, these speed up parameters are irrelevant (Boltzmann electrons, SC at fixed potential...).

Since SPIS v4.3, it is possible for the user to define the integration duration for the plasma and the populations (as e.g. for ambient ions). The compatibility with older SPIS versions is described in Time_steps_RC_4.3.

Name	Description	Variable type	Unit cf allowed units	Default value	In use
duration	Duration of the simulation NB: if the scenario PotentialSweep is selected, this duration is only used to determine the monitoring time steps.	float	[s]	0.0001	Yes
simulationDt	Maximum time step for global simulation dynamics. - If set to 0, it gets semi – automatic (but constant over the simulation), i.e. determined by lower level time step (plasma time step, which itself can be user-defined or semi-automatic). - If negative, automatic: absolute value is only considered as a maximum and dt is increased as much as possible within validity limits (validity of linear extrapolation of collected/emitted currents as a function of local potentials) starting from dt = simulationDtInit	float	[s]	0.0	Yes Automatic (negative) only since SPIS v4
simulationDtInit	Initial time step for global simulation dynamics (only used if automatic as a starting value).	float	[s]	0.01 s	Yes
fixedSimulationDtFlag	Flag to define the time step evolution mode: - If set to 0 : automatic calculation (as a function of the validity: maximum time step equal simulationDt), - If set to1 : fixed time step equal to SimulationDt (Infinite validity for the current scalers - if activated)	int	[-]	0	No
noCurrentScalerFlag	flag to disable (if set to 1) the current scalers dI/dV calculation (zero current variation assumed in the implicit circuit solver)	int	[-]	0	No
circuitSolverMode	flag to define the circuit solver mode: - If set to 0 : implicit solver - If set to 1 : explicit solver	int	[-]	0	No
plasmaDt	Time step for plasma dynamics. If set to 0, it gets semi automatic, i.e. determined by lower level time step (smallest time step allowed among matter populations).	float	[s]	0.0	Yes
plasmaDuration	Integration duration of the plasma dynamics : - If positive, constant duration fixed by user - If set to 0 or negative, equal to the upper level time step taking into account the SpeedUp: simulationDt / plasmaSpeedUp (compatibility with older versions).	float	[s]	0.0	Yes, since SPIS v4.3
plasmaSpeedUp	Numerical times speed-up factor for plasma. Plasma dynamics is only integrated over a fraction 1/plasmaSpeedUp of actual physical time (valid in quasi-steady conditions for plasma compared to SC floating potentials dynamics)	float	[-]	1.0	Yes
plasmaUnderRelaxTimeCstt	Under-relaxation time constant for plasma (0 => no under-relaxation). If not 0, at each step of the Poisson-matter loop: - Poisson eq. is solved, giving the Esoled solution - The new electric field is computed as (1-w)* Esoled + w*Eold where Eold is the old electric field, w = e^‑dt/underRelaxationTimeConstant a weight function, .and dt the time step of the loop. It amounts to underrelaxing with time constant plasmaUnderRelaxTimeCstt (leading e.g. to an exponential decay with this time constant in case a step-like variation of density in Poison eq.)	float	[s]	0.0	Yes
scenario	Name of the scenario used to run successive simulations (or simulation with externally-induced changes). The default value, scenario = "Scenario", is trivial (no changes). See the Scenario section for the general rules, the example of the PotentialSweep Scenario, and the meaning of the scenario parameters in this case.	string	[-]	Scenario	Yes
scenarioParameter1, scenarioParameter2, etc.	Scenario parameters, with a specific meaning depending on each Scenario. See the Scenario section for the meaning of the scenario parameters for the case of the PotentialSweep Scenario.	string	[-]		Yes
fixedDt	Flag to have fixed integration duration dt of all populations. If yes (0=no, 1=yes), the integration duration of each species (thisPopDt in the chart above) will be defined as each population dtMax parameter. Otherwise the physical integration duration dt of each species is equal to the plasmaDt (and its numerical dt is possibly reduced through speed up mechanism). A typical usage of fixedDt is to force integration over the duration needed for some populations to reach their steady states (e.g. electrons).	int	[-]	0	Yes, since SPIS v4

Back to top.

Plasma

This section defines the environment through two distributions of electrons and two of ions. The total should be neutral (not enforced).

The major point to be noted is that some of the parameters are names of classes. It means that Java generates a class from its name, which is possible thanks to the powerful introspection capabilities of Java. Reasonable defaults are provided for these classes, to which shy users can stick.

The general rule for the environmentType parameter, which defines the environment, is:

- this class must derive from the class Environment

- have a specific constructor including the UI-defined parameters as described in "Writing UI-supported classes" page and in ..\API\public\spis\Top\Plasma\Environment.html

- in practice as of today following these specifications only BiMaxwellianEnvironment has been implemented, which may involve two Maxwellians or only one by setting the second one(s) to zero density (as in the defaults)

The general rules for the ionDistrib* electronDistrib* parameters, which define the 4 particle populations (2 of ions, 2 electrons), is:

- these classes must derive from the class VolDistribWithIO

- have a specific constructor including the UI-defined parameters as described in "Writing UI-supported classes" page and in VolDistrib\VolDistribWithIO.html

- in practice in SPIS v4.0 the following distribution are available:

- GlobalMaxwellBoltzmannVolDistrib: describes a particle population as a global thermal equilibrium distribution (Maxwell-Boltzmann) and is usually valid when no attractive potential or potential barrier exists (density increase is limited to a linear variation for positive potential)

- UnlimitedGlobalMaxwellBoltzmannVolDistrib: similar Maxwell-Boltzmann distribution but density increase is not limited for positive potential (remains exponential)

- PICVolDistrib: really simulates this population dynamics but is much more costly in computation time and memory

- BackTrackingVolDistrib: computes currents onto spacecraft surface through backtracking (but does not compute densities!)

- BacktrackingBoltzmannCompositeVolDistrib: computes currents onto spacecraft surface through backtracking and densities through Boltzmann distribution

- BacktrackingPICCompositeVolDistrib: computes currents onto spacecraft surface through backtracking and densities through Boltzmann distribution

- HybridMZVolDistrib: hybrid multi-zone volume distribution: two different volume distributions are used in two different zones: Boltzmann in large density zone (quasi neutral) and PIC in lower density region, cf. Multi-physical modelling algorithms technical note

- NoSinkHMZVD: similar hybrid multi-zone volume distribution but this population is not in contact with a sink or unlimited source (as e.g. the ambient environment), hence a balance for these particles is to be computed (still experimented, limited stability, cf. Multi-physical modelling algorithms technical note)

- LocalMaxwellVolDistrib: simple constant distribution, mostly used for debugging.

The supported types of ions are currently H+, O+, H20+, Xe+, Xe++, Ar+, Cs+, In+ but can easily be increased (see the source of ..\API\public\spis\Top\Default\SpisDefaultPartTypes.html).

Name	Description	Variable type	Unit cf allowed units	Default value	In use
environmentType	Name of the Environment class to be used (ex: BiMaxwellianEnvironment which will use the parameters below, or WorstCaseGeoEnvironment which will be self-contained)	String / Class	-	BiMaxwellianEnvironment	Yes
electronDensity	electron density (1^st population)	float	[m^-3]	1.0e6	Yes
electronTemperature	Electron temperature(1^st population)	float	[eV]	1.0	Yes
electronDistrib	Name of the VolDistrib class to be used for electrons	String / Class	-	PICVolDistrib	Yes
electronDt	Maximum integration time step for electrons (1^st population), if relevant (for PIC but not for Boltzman). If negative, automatic determination by CFL-like criterion: not cross more than a fraction of a cell in a time step. Warning: acceleration by unexpected potentials may violate this criterion determined at particle injection.	float	[s]	-1.0	Yes
electronDuration	Maximum integration duration for electrons 1st population: - If positive, constant duration fixed by user - If set to 0 or negative, equal to the upper level time step taking into account the SpeedUp: plasmaDt / electronSpeedUp (compatibility with older versions).	float	[s]	0.0	Yes, since SPIS v4.3
electronSpeedUp	Numerical times speed-up factor for electrons (relevant for PIC only). Electrons are only moved of a fraction 1/electronSpeedUp of actual physical times (valid in quasi-steady conditions for electrons)	float	[-]	1.0	Yes
electronTrajFlag1	Plot ambient electron (1^st population) trajectory? 0=no, 1=yes NB: extra trajectory parameters must be defined	int	-	0	Yes (since SPIS v4.2)
ionDensity	ion density (1^st population)	float	[m^-3]	1.0e6	Yes
ionTemperature	Ion temperature (1^st population)	float	[eV]	1.0	Yes
ionVx	Ion drift velocity along x axis (1^st population)	float	[m/s]	0.0	Yes
ionVy	Ion drift velocity along y axis (1^st population)	float	[m/s]	0.0	Yes
ionVz	Ion drift velocity along z axis (1^st population)	float	[m/s]	0.0	Yes
ionType	First ion population: a string that must be found in the particle types list, including neutrals and electrons (special types of ions!)	String	-	H+	Yes (correct display of neutral densities and currents only since SPIS V4.3)
ionDistrib	Name of the VolDistrib class to be used for ions	String / Class	-	PICVolDistrib	Yes
ionDt	Maximum integration time step for ions. Automatic if negative.	float	[s]	-1.0	Yes
ionDuration	Maximum integration duration for ions 1st population (set to 0 for compatibility with older versions).	float	[s]	0.0	Yes, since SPIS v4.3
ionSpeedUp	Numerical times speed-up factor for ions.	float	[-]	1.0	Yes
ionTrajFlag1	Plot ambient ion (1^st population) trajectory? 0=no, 1=yes	int	-	0	Yes (since SPIS v4.2)
electronDensity2	electron density (2^nd population)	float	[m^-3]	1.0e6	Yes
electronTemperature2	Electron temperature(2^nd population)	float	[eV]	1000.0	Yes
electronDistrib2	Name of the VolDistrib class to be used for the 2^nd electron population	String / Class	-	PICVolDistrib	Yes
electronDt2	Integration time step for electrons (2^nd population). Automatic if negative.	float	[s]	-1.0	Yes
electronsDuration2	Maximum integration duration for electrons 2nd population (set to 0 for compatibility with older versions).	float	[s]	0.0	Yes, since SPIS v4.3
electronSpeedUp2	Numerical times speed-up factor for electrons (2^nd population).	float	[-]	1.0	Yes
electronTrajFlag2	Plot ambient electron (2^nd population) trajectory? 0=no, 1=yes	int	-	0	Yes (since SPIS v4.2)
ionDensity2	ion density (2^nd population)	float	[m^-3]	1.0e6	Yes
ionTemperature2	Ion temperature (2^nd population)	float	[eV]	1000.0	Yes
ionVx2	Ion drift velocity along x axis (2^nd population)	float	[m/s]	0.0	Yes
ionVy2	Ion drift velocity along y axis (2^nd population)	float	[m/s]	0.0	Yes
ionVz2	Ion drift velocity along z axis (2^nd population)	float	[m/s]	0.0	Yes
ionType2	Second ion population (a string that must be found in the particle types list)	String	-	H+	Yes
ionDistrib2	Name of the VolDistrib class to be used for ions 2^nd population	String / Class	-	PICVolDistrib	Yes
ionDt2	Integration time step for ions (2^nd population). Automatic if negative.	float	[s]	-1.0	Yes
ionDuration2	Maximum integration duration for ions 2nd population (set to 0 for compatibility with older versions).	float	[s]	0.0	Yes, since SPIS v4.3
ionSpeedUp2	Numerical times speed-up factor for ions (2^nd population).	float	[-]	1.0	Yes
ionTrajFlag2	Plot ambient ion (2^nd population) trajectory? 0=no, 1=yes	int	-	0	Yes (since SPIS v4.2)
avPartNbPerCell	average number of super-particle per cell NB: the average particle number per node is more relevant because computation is mostly on the nodes. It is 6 times bigger, this is why avPartNbPerCell can be rather small ~ 5	float	[-]	5.0	Yes
lmvdSubType	sub-type of the LocalMaxellVolDistrib: if an ion/elec distrib is declared LocalMaxellVolDistrib. It can be 'uniform', 'linear', 'stepwise', 'constant-linear' or 'bubble' (see in LocalMaxwellVolDistrib source for details)	String	[-]	uniform	Yes (since SPIS V4.0)

Back to top.

MultiZone

This section describes the fine tuning parameters for the MultiZone modelling (HybridMZVolDistrib) of a population.

They should only be modified by advanced users.

Beyond the short description below, the advanced user can find a detailed effect of these parameters in the source code of HybridMZVolDistrib.

Name	Description	Variable type	Unit cf allowed units	Default value	In use
jclfCVSpeed	convergence speed for jCL factor	float	[-]	1.0	Yes, Since SPIS V4.0
jclfPosChargeWeight	weighing factor for the presence of positive space charge in a positive sheath, which leads to jCLfact reduction to avoid instabilities	float	[-]	1.0	Yes, Since SPIS V4.0
jclfExtractingFieldWeight	weighing factor for the presence of an extracting electric field at boundary between zones, which leads to a jCLfact increase	float	[-]	1.0	Yes, Since SPIS V4.0
jclfReattractingFieldWeight	weighing factor for the presence of a re-attracting electric field at boundary between zones, which leads to a jCLfact reduction	float	[-]	1.0	Yes, Since SPIS V4.0
jclfSmoothing	smoothing strengh for jCL factor at each iteration	float	[-]	1.0	Yes, Since SPIS V4.0
jclfLowerBound	lower bound for jCL factor	float	[-]	0.01	Yes, Since SPIS V4.0
jclfUpperBound	upper bound for jCL factor	float	[-]	100.	Yes, Since SPIS V4.2
neLowerBoundCoeff	coefficient ruling the lower boundary on Ne estimate for jTh computation: small => less constraint, big => ne close to ni	float	[-]	1.0	Yes, Since SPIS V4.0
zoneBdElecDensification	densification coefficient (increases superparticle number, decreasing their weight) for PIC electrons emitted at zone boundary	float	[-]	1.0	Yes, Since SPIS V4.0
jclfAdjustLoopNb	number of loops for adjusting jCL factor within a HybridMZVolDistrib	integer	[-]	3	Yes, Since SPIS V4.0
hmzvdPoissonVlasovLoopNb	number of Poisson-Vlasov loops within each jCL factor adjusting iteration in a HybridMZVolDistrib	integer	[-]	3	Yes, Since SPIS V4.0

Back to top.

Poisson equation

Poisson boundary conditions are:

- always Dirichlet on the spacecraft (fixed potential), the initial potential being controlled by the global parameter initPotFlag (spacecraft section) and possibly defined locally (see the local parameters)

- Fourier on the external boundary (mixed Dirichlet-Neumann) with parameters defined so as to give an asymptotic behaviour in r^-n. Dirichlet is also possible on the external boundary (this eliminates the observed detrimental interactions at an edge between Fourier BCs on two nearby external surfaces when one of the Fourier is used to mimic a quasi Dirichlet BC).

They are controlled by the poissonBCType parameter.

The non-linear Poisson equation includes one (or two) Maxwellian distributions of electrons:

-Df = e(n_i - n_e1 e^ef/kTe1) / e₀ or -Df = e(n_i - n_e1 e^ef/kTe1 - n_e2 e^ef/kTe2) / e₀

where e n_i is the total charge density of other particles (usually PIC-modelled ions, but possibly also other PIC-modelled electrons), and n_ex is the electrons density of the x-th electron distribution (a scalar, contrarily to n_i which is a field) and T_ex its temperature.

If the non linear solver is selected (linearPoisson = 0), the Boltzmann electron distribution(s) of the environment (Plasma section above) are automatically inserted in the non-linear Poisson solver (but not electron distributions that you defined as PIC, which are handled like ions in the above non-linear equation).

The non-linear Poisson solver follows an implicit scheme (Newton type), which has the major advantage to be stable even for cells larger than Debye length.

The next parameters, controlling the maximum iteration number or tolerance of the conjugate gradient Poisson equation solver, are rather for specialists.

Name	Description	Variable type	Unit cf allowed units	Default value	In use
poissonBCType	Defines Fourier (alpha pot + d(pot)/dn = value) or Dirichlet boundary condition (pot = value) on computation box external boundary: 0- Use the BC defined as fields through plasma editor (BdFourAlpha and BdFourValue Fourier BC; or BdDiriPot Dirichlet BC) 1- alpha parameter mimicking a 1/r decay (~vacuum) 2- alpha parameter mimicking a 1/r^2 decay (~pre-sheath) 3- alpha parameter mimicking a 1/r^n decay, n being next parameter (poissonBCParameter1) NB: in any case, BC are Dirichlet on SC, defined by local plasma parameter SCDiriPot	int	-	2	Yes
poissonBCParameter1	Parameter that can be used by some BC types (e.g. 1/r^n exponent)	float	[varies]		Yes
poissonBCParameter2	2^nd parameter that can be used by some BC types	float	[varies]		No
linearPoisson	0- no: use non-linear Poisson equation solver (implicit Newton scheme): -∆Φ = [qi ni – e ne1 exp(eΦ/kTe1) – e ne2 exp(eΦ/kTe2)] / ε0 where ne1 = first electronDensity if a Boltzmann electron distribution is selected (same for 2^nd distribution). It can use a truncated electron exponential instead, depending on electron GlobalMaxwellBoltzmannVolDistrib subtype 1- yes: use linear Poisson solver: -∆Φ = (qi ni – e ne) / ε 0 the local electron density ne being possibly computed through a Boltzmann law (if selected), but computed with the old potential (i.e. not taking into account its evolution in the equation solving) NB: this distinction is meaningless if no Boltzmann distribution is selected => SPIS-NUM shifts to linear and emits a warning NB: in case of small Debye length (smaller than cell size), only non-linear solver is stable.	int	-	0	Yes
neutrality	If on (neutrality = 1), imposes neutrality instead of solving Poisson: qi ni – e ne1 exp(eΦ/kTe1) Only the first ambient electron density is considered, and it must be defined as an UnlimitedGlobalMaxwellBoltzmannVolDistrib (if a PICVolDistrib its PIC density would be taken into account) If off (neutrality = 0), regular Poisson computation	int	-	0	Yes Since SPIS V4.3
variableTe	If on (variableTe = 1) and neutrality is on, the temperature used in Boltzmann distribution in neutrality equation is derived from kB Te ne^–γ^+1 = constant NB: plugging this adiabatic law directly in Boltzmann distribution like this is physically wrong (one must go back to Boltzmann distribution derivation), but it was implemented for comparison to other codes, where this is sometimes done.	int	-	0	Yes Since SPIS V4.3
variableTeGamma	Gamma adiabatic exponent in the variable Te law above	float	[-]	1.1	Yes Since SPIS V4.3
variableTeConstant	Constant in the variable Te law above	float	[eV.m^3(γ-1)] i.e. computed from kBTe in [eV] and ne in [m^-3], but not checked by the code (user can fill in any unit)	1.	Yes Since SPIS V4.3
vacuum	If on (vacuum = 1) and linearPoisson is on, solves Laplace equation instead of Poisson (sets space charge to zero in Poisson eq.). If on (vacuum = 1) and linearPoisson is off, sets ion space charge to zero in Poisson eq. and uses regular Boltzmann equation (implicit solver). If off (vacuum = 0), performs a regular Poisson eq. resolution.	int	-	0	Yes Since SPIS V4.3
tolGradient	Tolerance for conjugate gradient Poisson Solver (stops when residue is smaller than tolGradient)	float	[-]	0.0001	Yes
iterGradientNl	Maximum iteration number for conjugate gradient Poisson Solver when non-linear solving	int	-	100	Yes
tolGradientNl	Tolerance for conjugate gradient Poisson Solver when non-linear solving	float	[-]	0.0001	Yes
iterNewton	Maximum iteration number for Newton algorithm in non-linear Poisson solving	int	-	50	Yes
tolNewton	Tolerance for Newton algorithm loop in non-linear Poisson solving	float	[-]	0.02	Yes
iterLinearSys	Maximum iteration number for linear system solver (used for capacitance matrix inversion)	int	-	10000	Yes
tolLinearSys	Tolerance for linear system solver (used for capacitance matrix inversion). May have to be further reduced when strongly multiscale SC mesh is used (resulting in very variable areas and capacitances of elements). If not, local surface potential is not solved on the smallest surface elements.	float	[-]	1e-8	Yes

Back to top.

B field

A uniform B field can be defined this way.

Name	Description	Variable type	Unit cf allowed units	Default value	In use
Bx	x-component of the magnetic field (uniform over the computation box)	float	[T]	0.0	Yes
By	y-component of the magnetic field	float	[T]	0.0	Yes
Bz	z-component of the magnetic field	float	[T]	0.0	Yes

NB: like in many domains, the solver can indeed handle more general situations, here a local B field, the restriction to a uniform B field coming from the UI only. A dipolar B field can thus e.g. easily be handled by coding it in the software (the only work is to generate such a local map; solvers are then apt to use it directly).

Back to top.

Spacecraft

If electricCircuitIntegrate = 0, spacecraft potentials are constant, if electricCircuitIntegrate = 1, the spacecraft floats, the relative capacitances being derived from material properties, whereas the spacecraft absolute capacitance is defined by the parameter CSat.

See Spacecraft circuit description for details on circuit model.

Name	Description	Variable type	Unit cf allowed units	Default value	In use
electricCircuitIntegrate	Flag controlling SC electric circuit integration: - 0: do not integrate (constant initial potentials) - 1: integrate	int	-	1	Yes
initPotFlag	Flag to define initial spacecraft potential - 0: set it to 0 - 1: uniform potential = initPot (next parameter) - 2: local potential defined via the UI (SCDiriPot, see local parameters below)	int	-	1	Yes
initPot	Initial global potential for the spacecraft (if initPotFlag =1)	float	[V]	0	Yes
CSat	Spacecraft absolute capacitance. It represents the capacitive coupling between spacecraft and infinity (the capacitance electrodes are the spacecraft and its sheath). This capacitance is spread over all electric nodes proportionally to their areas, i.e. split into several capacitors between infinity and the electric nodes grounds (as is the real capacitive coupling in space). An alternative is to define a negative Csat = -x. The absolute capacitance used is then x (positive), and it is plugged between infinity and spacecraft ground only (electric node 0) in that case. It can sometimes be useful. See Spacecraft circuit description.	float	-	1.0e-9	Yes
exactCSat	flag to ask for an exact computation of spacecraft capacitance (if > 0). More precisely Gauss theorem (integral Poisson equation) is used at each time step to determine the SC potential so as to insure exact charge conservation (a variable Csat is derived from that)	float	[-]	0.0	Yes, Since SPIS V4.0
electricCircuitFilename	Name of the file describing extra electric devices between electric (super-)nodes. See below for syntax of circuit file. The file must be in the "SpisUI/defaultValues" directory (if no project loaded) or your project directory (subfolder NumKernel/Input)	String	-	circuit.txt	Yes
validityRenormalisation	scaling parameter to globally renormalise validity of scalable currents	float	-	1.0	Yes, Since SPIS V4.2
smoothingPot	strength of spacecraft surface potential smoothing at each step (1.0 => 1 step on nearest elements, can be smaller or larger than 1.0)	float	-	0.0	Yes, Since SPIS V4.2

Circuit file syntax

The file describing the electric circuit is composed of an arbitrary number of lines, each with the syntax:

componentDescriptor node1Id node2Id value

with:

- componentDescriptor (a string) one of

- C : it is a capacitor of capacitance value

- R : it is a resistor of resistance value

- V : it is a voltage generator of potential difference value (V_node2 = V_node1 + value)

- node1Id and node2Id (integers): the Ids of the (super) electric nodes between which to plug the component (same Id as in ElecNodeId)

- value (a float): the value of the component (resistance…)

Example file :

V 0 1 -10

R 0 2 1.e6

C 0 3 1.e-10

C 2 3 1.e-10

- line 1: Electric super node 1 is biased of -10 V with respect to node 0, which is SC ground (it may be a Langmuir probe).

- line 2: Electric super node 2 is related by a 1 MW resistor to SC ground (it may be a solar array).

- line 3: Electric super node 3 is not related by any "real" component to SC ground, so it was chosen to model its capacitive coupling to the ground (this is not necessary, a fraction of SC absolute capacitance CSat is attributed to each electric node, proportionally to its area, so that it does not have zero capacitance, resulting in infinite potential as soon as it collects some charge).

- line 4: the capacitive coupling between nodes 2 and 3 has been added (seldom useful).

Back to top.

Particle sources on spacecraft

These parameters allow the embedding of a plasma sources on the spacecraft (e.g. a thruster). Several sources are allowed, currently 4, but their number can easily be increased by modifying DefaultGlobalParam.py in SpisUI/DefaultValues folder.

Each source is controlled by the following global parameters, which allow turning the source on, defining the source class and particle type. The general rules for the sourceType parameter, which defines the source class, is:

- this class must derive from the class NonPicSurfDistrib

- have a specific constructor including the UI-defined parameters as described in "Writing UI-supported classes" page and in ..\API\public\spis\Surf\SurfDistrib\NonPICSurfDistrib.html

- in practice as of today LocalMaxwellSurfDistrib, AxisymTabulatedVelocitySurfDistrib, TwoAxesTabulatedVelocitySurfDistrib, FowlerNordheimSurfDistrib and MaxwellianThruster are supported.

Extra local parameters allow to switch locally between the sources (sourceId), and to define their parameters (current, temperature, Mach number). It is up to the source model to use or not these local parameters. They will usually use the local source current density, but local temperature and Mach number were really designed for Maxwellian sources and may not be used by others (AxisymTabulatedVelocitySurfDistrib and TwoAxesTabulatedVelocitySurfDistrib use angular distributions defined in files, while FowlerNordheimSurfDistrib is self contained).

Multi-species/multi-sources on the same location are also supported. The rules to perform that are:

- declare sourceTypeX of source number X as a MultipleSurfDistrib

- define the number sourceNbX of its so-called "sub sources" (sourceX.Y is the Y^th sub source of sourceX)

- extra global parameters (sourceCurrentFactorX.Y, sourceTempFactorX.Y and sourceMachFactorX.Y) are used to define the multiplication factor to apply to local parameters (current, temperature, Mach number) which are initially defined for sourceX.

Name	Description	Variable type	Unit cf allowed units	Default value	In use
sourceFlag1	Flag for defining first artificial source on the spacecraft: 0 => not active, 1 => active, emitted particle dynamics modelled by PIC method, x>0 => same, but the number of super-particles is densified by x (for a local source, for which you want x times avPartNbPerCell particles per cell),	float	-	0	Yes
sourceType1	Name of the SurfDistrib class to be used for first artificial source on the spacecraft (ex: LocalMaxwellSurfDistrib, which will use the source flux, source temperature and source Mach user-defined local fields, whereas a specific EP model could only use the source flux and define internally its velocity distribution, see above)	String / Class	-	LocalMaxwellSurfDistrib	Yes
sourceParticleType1	Type of particles for first particle source (a string that must be found in the particle types)	String	-	Xe+	Yes
sourceDt1	Integration time step for 1^st source. Automatic if negative: determined so that the particle crosses a fraction of a cell by time step in the first cell (may not be true later because of velocity or cell size changes). See constraints on time steps.	float	[s]	-1.0	Yes
sourceDuration1	Maximum integration duration for 1^st source population (set to 0 for compatibility with older versions).	float	[s]	0.0	Yes, since SPIS v4.3
sourceSpeedUp1	Numerical times speed-up factor for 1^st source population.	float	[-]	1.0	Yes
sourceTrajFlag1	Plot source 1 trajectory? 0=no, 1=yes. NB: in the case source 1 is a multiple source, plot trajectories of each PIC sub source.	int	-	0	Yes (since SPIS V4.2)
sourceFlag2	Same as sourceFlag1, but for source 2	float	-	0	Yes
sourceType2	Same as sourceType1, but for source 2	String / Class	-	LocalMaxwellSurfDistrib	Yes
sourceParticleType2	Same as sourceParticleType1, but for source 2	String	-	electron	Yes
sourceDt2	Same as sourceDt1, but for source 2	float	[s]	-1.0	Yes
sourceDuration2	Same as sourceDuration1, but for source 2	float	[s]	0.0	Yes, since SPIS v4.3
sourceSpeedUp2	Same as sourceSpeedUp1, but for source 2	float	[-]	1.0	Yes
sourceTrajFlag2	Same as sourceTrajFlag1, but for source 2	int	-	0	Yes
sourceFlag3	Same for source 3	float	-	0	Yes
sourceType3	Same for source 3	String / Class	-	LocalMaxwellSurfDistrib	Yes
sourceParticleType3	Same for source 3	String	-	Cs+	Yes
sourceDt3	Same for source 3	float	[s]	-1.0	Yes
sourceDuration3	Same as sourceDuration1, but for source 3	float	[s]	0.0	Yes, since SPIS v4.3
sourceSpeedUp3	Same for source 3	float	[-]	1.0	Yes
sourceTrajFlag3	Same for source 3	int	-	0	Yes
sourceFlag4	Same for source 4	float	-	0	Yes
sourceType4	Same for source 4	String / Class	-	LocalMaxwellSurfDistrib	Yes
sourceParticleType4	Same for source 4	String	-	In+	Yes
sourceDt4	Same for source 4	float	[s]	-1.0	Yes
sourceDuration4	Same as sourceDuration1, but for source 4	float	[s]	0.0	Yes, since SPIS v4.3
sourceSpeedUp4	Same for source 4	float	[-]	1.0	Yes
sourceTrajFlag4	Same for source 4	int	-	0	Yes
sourceNb	Number of particle sources: if sourceNb is set to 5 to support a 5^th source, sourceFlag5, sourceType5 and sourceParticleType5, sourceDt5 and sourceSpeedUp5 must be defined. This can be done most conveniently in defaultGlobalParam.py (located in SpisUI/DefaultValues folder), but can also be done in GUI (modify sourceNb parameter and add parameters sourceFlag5, etc.).	int	-	4 (not to be modified carelessly, i.e. without creating extra parameters for extra sources)	Yes
fieldFactor	Field factor enhancement for Fowler-Nordheim sources (usually named beta)	float	[-]	1.0	Yes, since SPIS V4.0
sourceNb1	Number of particles sources of the multi-source 1 (only if source 1 is a MultipleSurfDistrib). If sourceNb1 is set to 3 to support a third sub sources, sourceFlag1.3, sourceType1.3 and sourceParticleType1.3, sourceDt1.3 and sourceSpeedUp1.3 must be defined, as well as sourceCurrentFactor1.3, sourceTempFactor1.3 and sourceMachFactor1.3 (if necessary). This can be done most conveniently in defaultGlobalParam.py (located in SpisUI/DefaultValues folder), but can also be done in GUI (modify sourceNb1 parameter and add parameters sourceFlag1.3, etc.).	int	-	0 (not to be modified carelessly, i.e. without creating extra parameters for extra sources)	Yes (since SPIS V4.2)
sourceFlag1.1	Same as for sourceFlag1, but for defining first sub source (source 1.1) of source 1 on spacecraft (only if source 1 is a MultipleSurfDistrib)	float	[-]	0	Yes (since SPIS V4.2)
sourceType1.1	Same as for source 1, but for source 1.1 (only if source 1 is a MultipleSurfDistrib)	String / Class	-	LocalMaxwellSurfDistrib	Yes (since SPIS V4.2)
sourceParticleType1.1	Same as sourceParticleType1, but for source 1.1 (only if source 1 is a MultipleSurfDistrib)	String	-	electron	Yes (since SPIS V4.2)
sourceDt1.1	Same as sourceDt1, but for source1.1 (only if source 1 is a MultipleSurfDistrib)	float	[s]	-1.0	Yes (since SPIS V4.2)
sourceDuration1.1	Same as sourceDt1, but for source1.1 (only if source 1 is a MultipleSurfDistrib)	float	[s]	0.0	Yes (since SPIS V4.3)
sourceSpeedUp1.1	Same as sourceSpeedUp1, but for source 1.1 (only if source 1 is a MultipleSurfDistrib)	float	[-]	1.0	Yes (since SPIS V4.2)
sourceCurrentFactor1.1	Multiplication factor used to define the current of sub source 1.1 with respect to its generating source 1 (current of source 1.1 = current of source 1 * sourceCurrentFactor1.1)	float	-	1.0	Yes (since SPIS V4.2)
sourceTempFactor1.1	Multiplication factor used to define the temperature of sub source 1.1 with respect to its generating source 1 (temperature of source 1.1 = temperature of source 1 * sourceTempFactor1.1)	float	-	1.0	Yes (since SPIS V4.2)
sourceMachFactor1.1	Multiplication factor used to define the mach number of sub source 1.1 with respect to its generating source 1 (Mach of source 1.1 = Mach of source 1 * sourceMachFactor1.1)	float	-	1.0	Yes(since SPIS V4.2)
sourceFlag1.2	Same as for sourceFlag1.1, but for defining second sub source (source 1.2) of source 1 on spacecraft	float	[-]	0	Yes
sourceType1.2	Same as for sourceType1.1, but for source 1.2	String / Class	-	LocalMaxwellSurfDistrib	Yes
sourceParticleType1.2	Same as sourceParticleType1.1, but for source 1.2	String	-	electron	Yes
sourceDt1.2	Same as sourceDt1.1, but for source1.2	float	[s]	-1.0	Yes
sourceDuration1.2	Same as sourceDuration1.1, but for source1.2	float	[s]	0.0	Yes (since SPIS V4.2)
sourceSpeedUp1.2	Same as sourceSpeedUp1.1, but for source 1.2	float	[-]	1.0	Yes
sourceCurrentFactor1.2	Same as sourceCurrentFactor1.1 but for source 1.2	float	-	1.0	Yes
sourceTempFactor1.2	Same as sourceTempFactor1.1 but for source 1.2	float	-	1.0	Yes
sourceMachFactor1.2	Same as sourceMachFactor1.1 but for source 1.2	float	-	1.0	Yes
sourceNb2	Same as sourceNb1 but for source 2	int	-	0 (not to be modified carelessly, i.e. without creating extra parameters for extra sources)	Yes
sourceNb3	Same as sourceNb1 but for source 3	int	-	0 (not to be modified carelessly, i.e. without creating extra parameters for extra sources)	Yes
sourceNb4	Same as sourceNb1 but for source 4	int	-	0 (not to be modified carelessly, i.e. without creating extra parameters for extra sources)	Yes

Back to top.

Surface interactions

Surface interactions are related to a population of particle, the one at the origin of the interaction (possibly with a specific handling as for photoemission).

They may or may not also be a source of particles (secondary emission does, but Radiation Induced Conductivity does not).

From the user viewpoint there are two types of interactions:

- a list of predefined interactions (photo-emission, SEE, erosion…)

- interactions handled on a generic basis, with the possibility to easily define new ones (since SPIS V4, only CathodeSpot is implemented)

They are described in the two subsections below.

A specific paragraph on the presence of a potential barrier on top of a sunlit surface (important for GEO charging) is to be found at the end of the first subsection.

Predefined surface interactions

These parameters are mostly flags to turn interactions on or off, see their definition in the table below.

For the definition of the interactions, see the classes implementing the interaction:

- Photo-emission: BasicPhotoEmInteractor

- Secondary emission from electrons: BasicSEEEInteractor, SEEEYieldFunction1, ElecBackscatterFunction

- Secondary emission from protons: BasicSEEPInteractor, SEEPYieldFunction1

- Induced conductivity: BasicInducedConductInteractor

- Erosion: ErosionInteractor, GRBOErosionYield, TonduErodedProductSampler

When invoked from UI, these Interactors use a GenericParamSet (since v4.3) witch is composed by a:

- Nascap Parameters for materials, described in NascapParamSet

- Erosion Parameters for materials, described in ErosionParamSet

with the database of built-in materials in SpisDefaultMaterials or using extended NASCAP based materials (since v4.3, see Material Properties).

Name	Description	Variable type	Unit cf allowed units	Default value	In use
photoEmission	- if 0, no photo-emission - if 1, photo-emission is turned on with the sun direction defined below (from sun vector (sunX...), no shading for now) - if 3, photo-emission is turned on with the sun direction defined below (from sun vector (sunX...)) and photo-electron dynamics is modelled (PIC) - if 5, photo-emission is turned on with a sun flux defined locally (local parameter sunFlux) - if 7, photo-emission is turned on with a sun flux defined locally (local parameter sunFlux)and photo-electron dynamics is modelled (PIC) NB: these values stem for a bit per bit definition: bit0 => on/off, bit1 => dynamics of photo-electrons is modelled / not, bit2 => sun flux locally defined / from sun direction (e.g. all on => binary 111 = decimal 7)	int	-	0 (off)	Yes
photoElectronTemperature	photo-electron temperature	float	[eV]	2.0	Yes
photoElectronDensification	Densification coefficient for photo electron superparticles: if different of 1, number of superparticles is multiplied by this parameter (and their weight divided accordingly)	float	-	1.0 (no densification)	Yes
photoElectronTrajFlag	Plot photo electron trajectory? 0=no, 1=yes	int	-	0	Yes (since SPIS V4.2)
sunX	x-component of sun direction (points to sun, vector opposite to photon velocity) NB if sun vector is not normalised and has norm x, the sun flux is multiplied by x (if x = 1, it is the real sun flux at 1 AU)	float	-	0.0	Yes
sunY	y-component of sun direction	float	-	0.0	Yes
sunZ	z-component of sun direction	float	-	1.0	Yes
electronSecondaryEmission	Bits go by groups of 3 : - bit 0: turn on secondary emission under electron impact (if 1), - bit 1: simulate secondary electron dynamics by PIC model (if 1), - bit 2 = model secondary emission form secondary electrons ("hoping") Six groups of 3 bits are used, successively for: - ambient electron population 1 - ambient electron population 2 - source 1 - source 2 - source 3 - source 4 Examples: - binary 011011 = decimal 30 => model secondary emission from both ambient populations, with secondary electron dynamics but no secondaries from secondaries - binary 111000000 = decimal 448 => model secondary emission from source 1 electrons with secondary electron dynamics and secondaries from secondaries ("hoping") NB: in the code, when turned on, the hoping is simulated by a second interactor, which is differentiated from the first interactor for primary electrons in the emittedCurrents.txt file. NB: when secondary emission is turned on for a multipleSurfDistrib source, it is turned on for each electron sub source.	int	-	0 (off)	Yes. NB: as of today, SEE from the two ambient populations cannot be controlled separately, SEE from ambient is either turned on globally or not (in practice a logical OR is computed between first and second groups of three bits)
electronSecondaryTemperature	secondary electron temperature from electron impact	float	[eV]	2.0	Yes
electronSecondaryDensification	Densification coefficient for secondary electron from electron superparticles: if different of 1, number of superparticles is multiplied by this parameter (and their weight divided accordingly)	float	-	1.0 (no densification)	Yes
electronSecondaryEmissionTrajFlag	Plot secondary emission electron under electron impact trajectory? 0=no, 1=yes	int	-	0	Yes (since SPIS V4.2)
protonSecondaryEmission	- if 0, no secondary emission under proton impact - if 1, secondary emission under ambient proton impact is turned on	int	-	0 (off)	Yes
protonSecondaryTemperature	secondary electron temperature from proton impact	float	[eV]	2.0	Yes
protonSecondaryDensification	Densification coefficient for secondary electron superparticles (from proton impact): if different of 1, number of superparticles is multiplied by this parameter (and their weight divided accordingly)	float	-	1.0 (no densification)	Yes
secondaryDt	Integration time step for all secondary electrons (under UV, electrons and protons). Automatic if negative, but may not be effective since fluxes are not known a priori => check resulting maximum and used time steps	float	[s]	-1.0 (automatic)	Yes
secondaryDuration	Maximum integration duration for all secondary electrons population (set to 0 for compatibility with older versions).	float	[s]	0.0	Yes, since SPIS v4.3
secondarySpeedUp	Numerical times speed-up factor for all secondary electrons (under UV, electrons and protons).	float	[-]	1.0 (no speed up)	Yes
volumeConductivity	- if 0, no volume conductivity - if 1, volume conductivity is turned on	int	-	0 (off)	Yes
inducedConductivity	- if 0, no induced conductivity - if 1, induced conductivity is turned on	int	-	0 (off)	Yes
surfaceConductivity	- if 0, no induced conductivity - if 1, induced conductivity is turned on	int	-	0 (off)	Yes
erosion	Similarly to electronSecondaryEmission, bits go by groups of 3 : - bit 0: turn on erosion (if 1), - bit 1: simulate eroded products dynamics by PIC model (if 1), - bit 2 = unused Six groups of 3 bits are used, successively for: - ambient ion population 1 - ambient ion population 2 - source 1 - source 2 - source 3 - source 4 Ex: all on = 011011011011011011 =112347 (or 111111111111111111 = 2^18-1 = 262143) NB: when erosion is turned on for a multipleSurfDistrib source, it is turned on for each ion sub source.
erosionProductDt	Maximum integration time step for erosion products (automatic if negative)	float	[s]	-1.0 (automatic)	Yes
erosionProductDuration	Maximum integration duration for erosion products (set to 0 for compatibility with older versions).	float	[s]	0.0	Yes, since SPIS v4.3
erosionProductSpeedUp	Numerical times speed-up factor erosion products	float	[-]	1.0 (no speed up)	Yes
erosionProductDensification	Densification coefficient for erosion product superparticles: if different of 1, number of superparticles is multiplied by this parameter (and their weight divided accordingly)	float	[-]	1.0 (no densification)	Yes
erosionProductsTrajFlag	Plot erosion products trajectory? 0=no, 1=yes	int	-	0	Yes (since SPIS V4.2)

The following parameters are used to turn on (barrierCSFlag) or tune (the next ones, for experts only) the CurrentScaler used by the implicit circuit solver when a potential barrier shows up on top of a photo-emissive surface.

The regular user should simply turn on this CurrentScaler through barrierCSFlag when such a situation is expected (typically charging in GEO in sunlight), while the advance user may enter into the source code of the derived classes of CurrentScaler for a more detailed understanding of the consequences of the tuning parameters.

Name	Description	Variable type	Unit cf allowed units	Default value	In use
barrierCSFlag	Flag for the current scaler specific to GEO potential barrier phenomenon for photo/secondary electron recollection (0 = off, 1 = on). To be turned on when potential barrier typical of GEO is expected.	int	-	0	Yes, since SPIS V4.0
bcsLocalFactor	local temperature factor for the current scaler specific to GEO potential barrier phenomenon (BarrierCurrentScaler) for photo/secondary electron recollection (for expert users only)	float	[-]	1.0	Yes, since SPIS V4.0
bcsGlobalFactor	global temperature factor for the current scaler specific to GEO potential barrier phenomenon (BarrierCurrentScaler) for photo/secondary electron recollection (for expert users only)	float	[-]	20.0	Yes, since SPIS V4.0
bcsRelValid	relative validity (relative to temp*bcsLocalFactor) for the current scaler specific to GEO potential barrier phenomenon (BarrierCurrentScaler) for photo/secondary electron recollection (for expert users only)	float	[-]	50.0	Yes, since SPIS V4.0
bcsSmoothPot	number of smoothing steps (each step => nearest elements) for the potential when the barrier current scaler is on (for expert users only)	int	[-]	6	Yes, since SPIS V4.0
bcsSmoothI	number of smoothing steps (each step => nearest elements) for the collected intensity when the barrier current scaler is on (for expert users only)	int	[-]	3	Yes, since SPIS V4.0
bcsSmoothdIdV	number of smoothing steps (each step => nearest elements) for dI/dV of recollected electrons when the barrier current scaler is on (for expert users only)	int	[-]	3	Yes, since SPIS V4.0

Generic surface interactions

Extra surface interactions can also be defined generically as a "plug in" class similarly ar for volume distributions, surface sources, etc.

Although only one of these classes was currently implemented (CathodeSpot), extra ones can easily be added as explained in .

The general rules for the interactorType* parameters, which define the model to be used (a class name), are:

- this class must derive from the class Interactor

- have a specific constructor including the UI-defined parameters as described in Surf\SurfInteract\Interactor.html

- in practice in SPIS v4.0 only CathodeSpot is available.

Name	Description	Variable type	Unit cf allowed units	Default value	In use
interactorFlag1	flag for defining an interactor on the spacecraft: 0 => none, 1 => yes, x => number of super-particles densified by x if relevant	float	[-]	0.0	Yes, since SPIS V4.0
interactorType1	Name of the Interactor class to be used for an interactor on the spacecraft (ex: CathodeSpot, which may also use the "source flux", "source temperature" and "source Mach" user-defined local fields)	String (Class name)	-	CathodeSpot	Yes, since SPIS V4.0
interactorParticleType1	Type of particles emitted by the interactor if it is an emitter (a string that must be found in the particle types)	String	-	O+	Yes, since SPIS V4.0
interactorDt1	Maximum integration time step for particles from interactor on SC (automatic if negative)	float	[s]	-1.0	Yes, since SPIS V4.0
interactorDuration1	Maximum integration duration for particles from interactor on SC (set to 0 for compatibility with older versions).	float	[s]	0.0	Yes, since SPIS v4.3
interactorSpeedUp1	Numerical times speed-up factor for particles from an artificial interactor on SC	float	[-]	1.0	Yes, since SPIS V4.0
interactorPopSource1	volume population to be used as source of the interaction of this interactor. It must be one of the predefined volume population names: - source1, source2, source3, source4 (indeed the PICVolDistrib alimented by source_x) - ions1, ions2, elec1, elec2 - photoElec, secondElec, secondElecUnderProton	String	-	Electrons1	Yes, since SPIS V4.0
interactorFlag2	Same as interactorFlag1 but for a possible 2^nd interactor	float	[-]		Yes, since SPIS V4.0
interactorType2	Same as interactorType1 but for a possible 2^nd interactor	String (Class name)	-		Yes, since SPIS V4.0
xxx2, xxx3…	…
interactorNb	Number of interactors. If it is e.g. 4, global parameters interactorFlag1 to interactorFlag4, interactorType1 to interactorType4, interactorParticleType1 to interactorParticleType4, etc. must be defined in UI	int	-	0	Yes, since SPIS V4.0

Back to top.

Volume interactions

These parameters allow to turn interactions on or off, define the type of interaction, the incoming and resulting populations and particle types.

The general rules for the volInteractType parameter, which defines the volume interaction type (class), are:

- this class must derive from the class VolInteractor

- have a specific constructor including the UI-defined parameters as described in "Writing UI-supported classes" page and in ..\API\public\spis\Vol\VolInteract\VolInteractor.html

- in practice as of today only CEXInteractor is implemented.

Name	Description	Variable type	Unit cf allowed units	Default value	In use
volInteractNb	Number of volume interactions	int	[-]	0	Yes, since SPIS v4.3
volInteract1, volInteract2, …	Flag to turn on 1st, 2nd, etc… volume interaction: 0 => off, 1 => on, x>0 => on, but the number of super-particles is densified by x.	float	[-]	0 (off)	Yes
volInteractType1, volInteractType2, …	Type of 1st, 2nd, etc…volume interaction. For now only CEXInteractor is supported (cf also CEX model documention). That choice has the following consequences: - inPop1VolInteract are the ions and must be a PICVolDistrib - inPop2VolInteract are the neutrals and can only be generated from an artificial surface source defined by a LocalMaxwellSurfDistrib	String/class	-	CEXInteractor	Yes
inPop1VolInteract1, inPop1VolInteract2, …	Defines first interacting population (ions for CEX) of 1st, 2nd, etc. volume interaction. Must be one of: - source1, source2, source3, source4 (indeed the PICVolDistrib alimented by source_x), or sourceX.Y - ions1, ions2, elec1, elec2 - photoElec, secondElec, secondElecUnderProton to select respectively a population issued from an artificial source, the ambient plasma, or a surface interaction.	String	-	source1	Yes
inPart1VolInteract1, inPart1VolInteract2, …	Type of particles for first interacting population (a string that must be found in the particle types) for the 1st, 2nd… volume interaction. NB: may be redundant with the definition of the interacting population, but has to be defined anyway.	String	-	Xe+	Yes
inPop2VolInteract1, inPop2VolInteract2, …	Defines second interacting population (neutrals for CEX) for 1st, 2nd… volume interaction. Must be one of: - source1, source2, source3, source4 (or sourceX.Y, etc.) - ions1, ions2, elec1, elec2 - photoElec, secondElec, secondElecUnderProton - fractionOfFirstPopSource, which is special feature for CEXInteractor applied to EP thrusters plume: the first population must be defined from an artificial source (inPop1VolInteract = source1, source2, sourceX.Y...) and this second population (of neutrals) will be emitted on the same SC surfaces, with a flux reduced with respect to the first one by a factor = parameter1VolInteract, and a uniform temperature equal to parameter2VolInteract [eV]. So, e.g. for a thruster of ionisation efficiency of 97% and neutrals emitted at 1160K, simply define parameter1VolInteract = 0.03 and parameter1VolInteract = 0.1 [eV].	String	-	fractionOfFirstPopSource	Yes
inPart2VolInteract1, inPart2VolInteract2, …	Type of particles for second interacting population (a string that must be found in the particle types) in 1st, 2nd, … volume interaction	String	-	Xe	Yes
outPart1VolInteract1, outPart1VolInteract2, …	Type of particles for first produced population (a string that must be found in the particle types) in 1st, 2nd, … volume interaction.	String	-	Xe+	Yes
outPop1DtVolInteract1, outPop1DtVolInteract2, …	Integration time step of first produced population in 1st, 2nd, … volume interaction. Automatic if negative.	float	[s]	-1.0	Yes
outPop1DurationVolInteract1, outPop1DurationVolInteract2, …	Maximum integration duration of first produced population (set to 0 for compatibility with older versions) in 1st, 2nd, … volume interaction	float	[s]	0.0	Yes, since SPIS v4.3
outPop1SpeedUpVolInteract1, outPop1SpeedUpVolInteract2, …	Numerical times speed-up factor for first produced population in 1st, 2nd, … volume interaction	float	[-]	1.0	Yes
outPop1VolInteractTrajFlag1, outPop1VolInteractTrajFlag2, …	plot 1^st produced population trajectory? 0=no, 1=yes	int	None	0	No
outPart2VolInteract1, outPart2VolInteract2, …	Type of particles for second produced population (a string that must be found in the particle types) in 1st, 2nd, … volume interaction. NB: not used in the current version of CEXInteractor, but might be later ("fast" neutrals)	String	-	Xe	No
outPop2DtVolInteract1, outPop2DtVolInteract2, …	Integration time step of second produced population in 1st, 2nd, … volume interaction. Automatic if negative.	float	[s]	-1.0	No
outPop2DurationVolInteract1, outPop2DurationVolInteract2, …	Maximum integration duration of second produced population (set to 0 for compatibility with older versions) in 1st, 2nd, … volume interaction.	float	[s]	0.0	No
outPop2SpeedUpVolInteract1, outPop2SpeedUpVolInteract2, …	Numerical times speed-up factor for second produced population in 1st, 2nd, … volume interaction.	float	[-]	1.0	No
outPop2VolInteractTrajFlag1, outPop2VolInteractTrajFlag2, …	plot 2^nd produced population trajectory? 0=no, 1=yes	int	None	0	No
crossSectionVolInteract1, crossSectionVolInteract2, …	Cross section for 1st, 2nd … volume interaction. Can be either: - a float: the value of the cross section s [m^2] - a String: the name of the file (to be found in folder SpisUI/DefaultValues or in your project NumKernel/Input folder later) where the cross section versus energy is defined (two ASCII columns E[eV], s [m2]) (see below for its format) The rule is the following: an attempt o traduce this String into a float, of which success depends the switching to first or second option	String	- None if file name - [m^2] if a cross section value	1.0e-18 (typical for Xe at 20 km/s)	Yes
parameter1VolInteract1, parameter1VolInteract2, …	1^st parameter of 1st, 2nd, …volume interactor - for CEX : if parameter3VolInteract=0, it is the ratio between neutral and ion fluxes at source surfaces.	float	[depends on interactor]	0.05	Yes
parameter2VolInteract1, parameter2VolInteract2, …	2^nd parameter of 1st, 2nd, …volume interactor - for CEX : temperature of neutrals	float	[depends on interactor]	0.1	Yes
parameter3VolInteract1, parameter3VolInteract2, …	3^rd parameter of 1st, 2nd, … volume interactor - for CEX: flag to turn on the lambertian distribution (0) or constant neutral density (1)	float	[depends on interactor]	0.0	Yes
parameter4VolInteract1, parameter4VolInteract2, …	4^th parameter of 1st, 2nd, …volume interactor - for CEX: if parameter3VolInteract=1, it is the pressure in default unit (kg/m/s2)	float	[depends on interactor]		Yes

Example of cross section definition file:

E (eV) cross section (m2)

0.0 2.0e-18

100.0 1.2e-18

300.0 1.0e-18

1000.0 .9e-18

The syntax is:

- first line = header (unread)

- next lines: energy in eV and cross section in square meters (separator = space)

Remark: it is still possible to use the single volume interaction version by setting the parameters volInteract to parameter4VolInteract (without numbering as in volInteract1). In that case, it is not possible to define multiple volume reactions. It may be the case when using projects built with a version older than SPIS4.3.

Back to top.

Outputs

These parameters mostly the periodicity for storing data for postprocessing (these data are then returned to UI and can be plotted).

Two last parameters tune the detail level for screen printing (or verbosity level).

Name	Description	Variable type	Unit cf allowed units	Default value	In use
scPotMonitorStep	time step for spacecraft ground potential monitoring (0.0 => none, -n => n times) NB: used also for currents and potentials on each electric (super) node	float	[s]	-100.0	Yes
scPotMapMonitorStep	time step for spacecraft local potential monitoring (0.0 => none, -n => n times)	float	[s]	-10.0	Yes
scElecFieldMapMonitorStep	time step for spacecraft electric field monitoring (0.0 => none, -n => n times)	float	[s]	-10.0	Yes, since SPIS v4.3
scCurrentMapMonitorStep	time step for spacecraft local currents monitoring (0.0 => none, -n => n times)	float	[s]	-10.0	Yes
plasmaPotMapMonitorStep	time step for plasma potential monitoring (0.0 => none, -n => n times)	float	[s]	-10.0	Yes
plasmaElecFieldMapMonitorStep	time step for plasma electric field monitoring (0.0 => none, -n => n times)	float	[s]	-10.0	Yes, since SPIS v4.3
densitiesMapsMonitorStep	time step for densities monitoring (0.0 => none, -n => n times)	float	[s]	-10.0	Yes
currentMapMonitorStep	time step for current density vector monitoring (0.0 => none, -n => n times)	float	[s]	-10.0	Yes
energyMapMonitorStep	time step for kinetic energy monitoring (0.0 => none, -n => n times)	float	[s]	-10.0	Yes
densityLogPlotFlag	plot log10 of densities? 0=no, 1=yes(log only), 2=both	int	-	2	Yes
currentLogPlotFlag	plot log10 of currents? 0=no, 1=yes(log only), 2=both	int	-	2	Yes
densityLogPlotCutoff	cutoff for density log plots	float	[#/m^3]	0.001 m^-3	Yes
currentLogPlotCutoff	cutoff for current log plots	float	[A/m^2]	10^-12 A/m^2	Yes
densityChargeState	control of output density type, either amu/m3 or #/m3, 1=amu/m3, 2=#/m3, 4=automatic (from known particle type)	int	-	4	Yes (since SPIS V4.3)
fluxChargeState	control of output collected fluxes type, either C/m2/s = A/m2 (i.e. a current) or #/m2/s (i.e. a flux), 1=currents, 2=fluxes, 4=automatic (from known particle type)	int	-	4	Yes (since SPIS V4.3)
cumulateBetweenSteps	cumulate currents and densities between monitoring steps for improved statistics (0=no, 1=yes(improved only), 2=both)?	int	-	1	Yes
finalCumulation	cumulate currents and densities at the end of simulation ? 0=no, 1or2=yes	int	-	2	Yes
finalCumulationStartTime	if finalCumulation=1 starting time for final dens-current cumulation, if finalCumulation=2 fraction of the simulation at which cumulation starts	float	[s] or [-]	0.5	Yes
numericsMonitorStep	time step for monitoring of the numerical behaviour of the simulation (0.0 => none, -n => n times)	float	[s]	-100.0	Yes
numericsMapsMonitorStep	time step for numerical behaviour monitoring through 3D maps of superparticle numbers, one in #/element and one in #/node (0.0 => none, -n => n times)	float	[s]	-10.0	Yes (since SPIS V4.3)
materialPropertyPlots	plot material properties? 0=no, 1=yes	int	-	0	Yes
verbose	Verbosity level (level of screen messages about code execution): 0 = no print at all 1 = prints errors and warnings only 2 = 1 + minimal information 3 = 1 + more information (remains yet readable) 4 = even more information … (next levels for debugging)	int	-	3	Yes
poissonVerbose	Same as verbose, but specific to Poisson solver	int	-	3	Yes
particleTrajectoriesNb	Number of particle trajectories per PIC population. NB: max number of 1000 trajectories per population.	int	-	0	Yes (since SPIS V4.2)
particleTrajectoriesPeriod	Period used for trajectories of PIC populations	int	-	1	Yes (since SPIS V4.2)

Back to top.

Scenario

The default Scenario is Scenario, which is transparent (no real scenario, everything in and out is simply transferred from/to the top level Scenario to/from the regular Simulation).

Generic "plug-in" scenarios can be implemented and easily integrated. The general rules for the scenario parameter, which defines the Scenario type (class), are:

- this class must derive from the class Scenario

- have a specific constructor including the UI-defined parameters as described in "Writing UI-supported classes" page and in Scenario

In practice as of today the only non trivial scenario implemented is PotentialSweep. It consists in chaining successive simulations for different surface potentials. Results are extracted in the form of current-voltage (IV) characteristics for the populations, nodes, types of current selected.

When PotentialSweep is in use, the scenario parameters are understood the following way:

Name	Description	Variable type	Unit cf allowed units	Default value	In use
scenarioParameter1	Number of steps of the potential sweep	int	[-]	0	Yes
scenarioParameter2	Initial voltage (only used for monitoring) NB: this voltage and the Final voltage of scenarioParameter3 define the table of potentials used in the results files (and not the potential of each node)	float	[V]	0.0	Yes
scenarioParameter3	Final voltage (only used for monitoring)	float	[V]	1.0	Yes
scenarioParameter4	Duration of first I-V step NB: if PotentialSweep is in use, the parameter duration is used for monitoring concerns only.	float	[s]	2.e-6	Yes
scenarioParameter5	Duration of following I-V steps	float	[s]	1.e-6	Yes
scenarioParameter6	Fraction of step duration used for I-V sweeps results (smoothing)	float	[-]	0.5	Yes
scenarioParameter7	Flag for populations monitored. Populations taken into account for I-V sweeps: bits for populations to be taken into account. 9 bits are used for successive: - all populations - elec1 - elec2 - ions1 - ions2 - source1 - source2 - source3 - source4 ex: binary 000100011 = decimal 35 enables I- V sweep for all populations, elec1 and source1. ex: decimal -1 makes IV sweeps for each population	int	[-]	-1	No (all populations monitored since SPIS V4.3)
scenarioParameter8	Flag for nodes monitored during I-V sweeps if -1: all nodes; else: minimum and maximum nodes Id to be defined	int	[-]	-1	Yes
scenarioParameter9	Minimal Id node number for monitoring	int	[-]	0	Yes
scenarioParameter10	Maximal Id node number for monitoring	int	[-]	0	Yes
scenarioParameter11	Flag for type of current monitored (collected or emitted) - 0: all - 1: collected - 2: emitted NB: no SEE, photoelectrons and CEX interaction particles are not taken into account	int	[-]	0	Yes
scenarioParameter12	Number of nodes whose potential changes. For each node, the potential sweep is linear between the initial and final voltages.	int	[-]	0	Yes
scenarioParameter13	Id of 1st node with pot change	int	[-]	0	Yes
scenarioParameter14	Initial potential of 1st node	float	[V]	0.0	Yes
scenarioParameter15	Final potential of 1st node	float	[V]	1.0	Yes
scenarioParameter16	Id of 2nd node with pot change	int	[-]	0	Yes
scenarioParameter17	Initial potential of 2nd node	float	[V]	0.0	Yes
scenarioParameter18	Final potential of 2nd node	float	[V]	1.0	Yes
scenarioParameter(13+3*(i-1))	Id of i-th node with pot change	int	[-]	0	Yes
scenarioParameter(13+3*(i-1)+1)	Initial potential of i-th node	float	[V]	0.0	Yes
scenarioParameter(13+3*(i-1)+2)	Final potential of i-th node	float	[V]	1.0	Yes

Back to top.

Local parameters

These local parameters are scalar fields living either in the volume or on a surface (spacecraft or external boundary). Not all of them are used in the present version of the code. Some come in addition to global parameters that they override when some flag declares that a property is to be considered as local (e.g. turning on an interaction only locally).

They can be defined through the group editor , which is launched by the Groups/Group editot menu or the Edit groups button. It allows to define them group by group (a uniform value on each group).

See the UI documentation for practical usage of the group editor. We simply edict the basic principles here:

- in the CAD tool the user defines:

1. spacecraft surface (physical) groups

2. external boundary groups

3. volume groups

- in the group editor, for each of these 3 types of groups, a plasma must be defined:

1. a plasma of type spacecraft for spacecraft surface groups

2. a plasma of type boundary for boundary surface groups

3. a plasma of type volume for volume groups

These 3 types of plasma must not be mixed (they involve flags telling the solvers what is the spacecraft or the boundary!). In each of the 3 categories you have a choice among a few predefined “plasmas”, and extra ones that you can modify. Trying to add new plasma through the UI is possible but difficult, prefer modification of the extra ones (adding a new one is easier in the source code, see SpisUI/Bin/MaterialMaker.py, where the default materials are defined).

- for the spacecraft surface groups only, you MUST also choose a material and an electric node (even though the electric nodes are not yet used by the solvers, they must be defined). There again, you have a choice among a few predefined materials and electric nodes, and extra ones that you can modify (same thing about adding new ones).

The local fields are described now. They are grouped somewhat arbitrarily as Material, Electric Node, or Plasma properties. Affecting a given Material, Electric Node, and Plasma to a group affects their properties to each elements of the group.

NB: Only the properties that should be modified by the users are described here. You will find a few others in the Material, Electric Node, and Plasma editors (flags, xyz coordinates…) which should not be modified indeed.

Material properties

The major parameters are:

- the material model Id, which can only be 0 for now, but may be different when other material models are developed (0, means NASCAP-like i.e. at least based on NASCAP material properties database

- the material type Id is an Id which refers to the default material list in SPIS (currently coded in ..\API\public\spis\Top\Default\SpisDefaultMaterials.html), which is:

- 0: ITOC (Material coated with ITO)

- 1: CERS (Solar cell material. Cerium doped silicon with MgF2 coating)

- 2: CFRP (Carbon fibre, conducting, no resin layer)

- 3: KAPT (Kapton, average values for SEE. Usually more conductive under space irradiation)

- 4: COSR (Optical solar reflector without MgF2 coating. Cerium doped glass type MARECS/ECS)

- 5: EPOX (Epoxy. Thin layer of Epoxy resin on (conducting) Carbon fibre)

- 6: BLKP (Non conductive black paint. SEE yields are as measured for Electrodag 501)

- 7: BLKH (Non conductive black paint HERBERTS 1002-E. Values updated 3.10.88. Conduct. measured by ESTEC, SEE yield by DERTS)

- 8: BLKC (Conductive black paint Electrodag 501)

- 9: PCBZ (White paint PCB-Z assumed to be conductive in space)

- 10: PSG1 (White paint PSG 120 FD assumed to be conductive in space. Becomes conductive and FLUORESCENT under irradiation. SEE measurements by DERTS)

- 11: TEFL (Teflon, DERTS measurements of SEE)

- 12: CONT (Generic Dielectric after 5 years in GEO environment.)

- 13: GOLD

- 14: SILV (Silver as from NASCAP library)

- 15: ALOX (Oxydized Aluminium. SEE yields from DERTS for Aluminium/Kapton)

- 16: STEE (Steel, SEE sigma +Emax from DERTS, curve shape from CONT material)

but can be extended easily modifying built-in material in NUM (see the source code of ..\API\public\spis\Top\Default\SpisDefaultMaterials.html) or using extended NASCAP based materials (since v4.3).

The extended NASCAP based materials are defined in an external xml file (see example in SpisUI/NascapMaterials.xml) by its name and the 19 NASCAP properties (see NascapParamSet). Extended material properties (optional) can be added for a material like the sublimation energy needed for the ErosionParamSet and should be define as follow:

<ExtendedSpisProperty Name="SUBE" Value="5.0" Type="float" Unit="[eV]" Description="Sublimation energy">

WARNING: in one simulation all the materials should be defined from built-in material or extended NASCAP based materials, not the both, combination is not permitted.

The predefined materials-plasma-electric_node that can be affected to each physical group are defined in SpisUI/Bin/MaterialMaker.py file, which can easily be modified (see SPIS/UI documentation on this topic, when available).

Name	Description	Unit cf allowed units	Default value	Live on (spacecraft, external boundary or volume):	Centring, or localisation (0=node, 1=edge, 2=surface, 3=volume)	In use
MatModelId	Id of the material model used for this material	-	0 (default model = NASCAP-properties-based)	SC	2	Yes
MatTypeId	Id of this material in its material model	-	-1 (no coating: bare metal, no interaction (except collection))	SC	2	Yes
MatThickness	Material thickness (if defined, overrides the default material thickness defined in the material properties)	[m]	-1 (use the default material thickness defined in the material properties)	SC	2	Yes
PhotoEmis	If 1, photo emission is turned on locally and simulated	-	0 (no photo emission)	SC	2	No (global flag only is under use)
ElecSecEmis	If 1, secondary electron emission under electron impact is turned on locally and simulated	-	0 (no electron secondary emission)	SC	2	No (global flag only is under use)
ProtSecEmis	If 1, secondary electron emission under proton impact is turned on locally and simulated	-	0 (no ion secondary emission)	SC	2	No (global flag only is under use)
VolConduct	If 1, volume conductivity through the bulk material is turned on locally	-	0 (no volume conductivity)	SC	2	No (global flag only is under use)
IndConduct	If 1, induced volume conductivity is turned on locally and simulated (if 0, the raw volume conductivity above is used)	-	0 (no induced conductivity)	SC	2	No (global flag only is under use)
SurfConduct	If 1, surface conductivity is turned on locally and simulated (from the top of a cell to the next ones)	-	0 (no surface conductivity)	SC	2	No (global flag only is under use)
Temperature	Surface temperature	[K]	300.0	SC	2	No (needed by no interaction for now)
SunFlux	Sun flux on spacecraft, normalised to sun flux at 1 AU (only used when global parameter photoEmission = 5 or 7)	[sun at 1 AU]	1.0	SC	2	Yes

Back to top.

Electric node properties

There is the only one property resulting of the choice of an electric node, its Id.

Name	Description	Unit cf allowed units	Default value	Live on (spacecraft, external boundary or volume):	Centring, or localisation (0=node, 1=edge, 2=surface, 3=volume)	In use
ElecNodeId	The electric (super) node this element is related to (SC ground, array ground…)	-	0 (default electric node, related to SC ground)	SC	2	Yes

Back to top.

Plasma properties

The next ones result of the choice of a plasma, which was commented in the introduction to this Local Parameters section. Only SCDiriPot, SourceCurrent, SourceTemp, and SourceMach are in use now.

Name	Description	Unit cf allowed units	Default value	Live on (spacecraft, external boundary or volume):	Centring, or localisation (0=node, 1=edge, 2=surface, 3=volume)	In use
SurfThicknessS	Thickness of 2D surfaces (used when surfaces are tagged as thin, their thickness not meshed)	[m]	0.0	SC	2	Yes
EdgeRadiusS	Radius of 1D elements (used when edges are tagged as physical thin wires, their thickness not meshed)	[m]	0.0	SC	1	Yes
SCDiriFlag	If 1, Dirichlet condition for Poisson equation on SC (fixed potential)	-	1 (yes)	SC	0	No: set to 1, always Dirichlet on SC
SCDiriPotl	The potential to be used for Dirichlet condition	[V]	0.0	SC	0	Yes
SCFourFlag	If 1, Fourier condition for Poisson equation on SC: alpha pot + d(pot)/dn = value	-	0 (no)	SC	2	No: set to 0, always Dirichlet on SC
SCFourApha	Alpha parameter in Fourier condition: alpha pot + d(pot)/dn = value	[m^-1]	1.0	SC	2	No: always Dirichlet on SC
SCFourValue	Right hand side parameter in Fourier condition : alpha pot + d(pot)/dn = value NB: note the centring different from other Fourier parameters	[V/m]	0.0	SC	0	No: always Dirichlet on SC
BdDiriFlag	If 1, Dirichlet condition for Poisson equation on external boundary (fixed potential)	-	0 (no)	Boundary	0	Yes, Since SPIS V4.0 (used to be Fourier only)
BdDiriPot	The potential to be used for Dirichlet condition	[V]	0.0	Boundary	0	Yes, Since SPIS V4.0
BdFourFlag	If 1, Fourier condition for Poisson equation on external boundary	-	1 (yes)	Boundary	2	Yes, Since SPIS V4.0
BdFourAlpha	Alpha parameter in Fourier condition: alpha pot + d(pot)/dn = value (used if poissonBCType = 0)	[m^-1]	1.0 [m^-1]	Boundary	2	Yes
BdFourValue	Right hand side parameter in Fourier condition: alpha pot + d(pot)/dn = value (used if poissonBCType = 0)	[V/m]	0.0	Boundary	0	Yes
SourceId	Id of the local artificial plasma source defined on the spacecraft: between 1 and sourceNb (=4) to have source 1 to 4 emitting at this place. Value 0 or negative => no source. NB: only one source can be selected on each mesh element.	-	-1 (no source)	SC	2	Yes
SourceCurrent	Emitted current, or flux, of an artificial source defined on the spacecraft. NB: As each local parameter, SourceCurrent has only one unit during a single simulation. The first defined spacecraft source imposes the unit of currents to other ones. It is preferable to set the same units for all sources.	[A/m2], [#/m2/s], or [kg/m2/s] cf allowed units	0.0	SC	2	Yes (flux units, [#/m2/s], or [kg/m2/s], only since SPIS V4.3)
SourceTemp	Temperature of the emitted Maxwellian distribution, if sourceType of the corresponding sourceId (hence sourceType1 where sourceId = 1, or sourceType2 where sourceId = 2, etc.) is a LocalMaxwellSurfDistrib (if not, the interpretation of this value can be different, see each class description)	[eV]	1.0	SC	2	Yes
SourceMach	Source Mach number (0 => Lambertian). The exact definition of this parameter can be different depending on the surface distribution using it (see e.g. MaxwellianThruster, while LocalMaxwellSurfDistrib does not use it and only generates local Lambertian distributions)	[-]	0.0	SC	2	Yes
IncomPart	- If 0, no particle are injected. - If 1, particles are injected (following the defined environment)	-	1 (injection)	Boundary	2	Yes (since SPIS V4.2)
OutgoPart	- If 0, outgoing particles are lost (sink) - If 1, they bounce specularly (extra options possible)	-	0 (sink)	Boundary	2	Yes (since SPIS V4.2)
VolInteracFlag	If 1, volume interaction is computed locally in that region (typically charge exchange)	-	0 (no)	Volume	3	No (global flag only is under use)
BackgroundDens	Fixed background density used to compute volume interaction (typically: neutral density)	[m^-3]	0.0	Volume	3	No

Back to top.