FieldDynamics for Electrostatic Simulations¶
This page describes the Field options available for electrostatic simulations, that is,
when the field solver in the Basic Settings
element is set to electrostatic.
Fields¶
- Phi
The electric potential field. This field is un-editable, and is calculated automatically.
- Charge Density
The charge density field. This field is un-editable, and is calculated automatically.
- Electric Field
The Electric Field. This field is un-editable, and is calculated automatically.
- Background Charge Density
The background charge density field. This field can be added to a simulation by right clicking “Fields”, hovering over “Add Field”, then clicking “Background Charge Density”. You may add many Background Charge Densities to your simulation.
- expression
The value of the background charge density field. Can be a constant, a parameter, or a function of space and time.
- External Field
An External Field can be added to a simulation by right clicking “Fields”, hovering over “Add Field”, then clicking “External Field”. An external field will be added after the field solve and effect particle movements in the simulation.
- description
A space to provide a descriptive comment for the field.
- field type
In electrostatic simulations only magnetic fields may be added.
- field specification
Either import h5 file or function defined.
import h5 file A vis schema compliant h5 file. It does require that the file be in the same directory as the simulation. An error message will be provided if the file fails to import.
- filename:
The name of the .hdf5 file to be imported. Typical convention is simulationName_fieldName_dumpNum.h5
- lower bound 0:
The cell index of the 0th component lower bound of the source field, to be imported to the matching index in the simulation. If left not applicable the entire field will be imported.
- lower bound 1:
The cell index of the 1st component lower bound of the source field, to be imported to the matching index in the simulation. If left not applicable the entire field will be imported.
- lower bound 2:
The cell index of the 2nd component lower bound of the source field, to be imported to the matching index in the simulation. If left not applicable the entire field will be imported.
- upper bound 0:
The cell index of the 0th component upper bound of the source field, to be imported to the matching index in the simulation. If left not applicable the entire field will be imported.
- upper bound 1:
The cell index of the 1st component upper bound of the source field, to be imported to the matching index in the simulation. If left not applicable the entire field will be imported.
- upper bound 2:
The cell index of the 2nd component upper bound of the source field, to be imported to the matching index in the simulation. If left not applicable the entire field will be imported.
- function defined
Allows for manual specification of each component of the field
- component 0:
The function defining the field in the 0th component. Can be a time varying function
- component 1:
The function defining the field in the 1st component. Can be a time varying function
- component 2:
The function defining the field in the 2nd component. Can be a time varying function
- time dependent:
Set to true if any of the functions are time varying. The function will then be recalculated at each time step.
import h5 file by grid index A vis schema compliant h5 file. It does require that the file be in the same directory as the simulation. An error message will be provided if the file fails to import. This variant requires specifying the grid indices of both the source field to import as well as the indices of where to place that field in the simulation. This can be used to translate fields in position from a previous run to a new one.
The total number of cells between the source lower and upper bounds must match that of the simulation lower and upper bounds.
- filename:
The name of the .hdf5 file to be imported. Typical convention is simulationName_fieldName_dumpNum.h5
- source lower bound 0:
The grid index of the lower bound of the 0th dimension of the source field to be imported.
- source lower bound 1:
The grid index of the lower bound of the 1st dimension of the source field to be imported.
- source lower bound 2:
The grid index of the lower bound of the 2nd dimension of the source field to be imported.
- source upper bound 0:
The grid index of the upper bound of the 0th dimension of the source field to be imported.
- source upper bound 1:
The grid index of the upper bound of the 1st dimension of the source field to be imported.
- source upper bound 2:
The grid index of the upper bound of the 2nd dimension of the source field to be imported.
- simulation lower bound 0:
The grid index corresponding to the lower bound of the 0th dimension where the field will be placed in the simulation.
- simulation lower bound 1:
The grid index corresponding to the lower bound of the 1st dimension where the field will be placed in the simulation.
- simulation lower bound 2:
The grid index corresponding to the lower bound of the 2nd dimension where the field will be placed in the simulation.
- simulation upper bound 0:
The grid index corresponding to the upper bound of the 0th dimension where the field will be placed in the simulation.
- simulation upper bound 1:
The grid index corresponding to the upper bound of the 1st dimension where the field will be placed in the simulation.
- simulation upper bound 2:
The grid index corresponding to the upper bound of the 2nd dimension where the field will be placed in the simulation.
- nodalE
This is a node centered electric field, used for calculating particle movements. It cannot be added to a simulation but is created automatically and will be visible if dump nodal fields = true.
- nodalB
This is a node centered magnetic field, used for calculating particle movements. It cannot be added to a simulation but is created automatically and will be visible if dump nodal fields = true.
- invEps
This is a field that stores the inverse values of dielectrics in a simulation. It cannot be added in the Fields tab but is created automatically if necessary and can be visualized.
- D
This is the displacement field, only created if a dielectric is present in the simulation. It cannot be added in the Fields tab but is created automatically if necessary and can be visualized.
Initial Condition¶
To add an Initial Condition to a field, right-click on the field and select Add FieldInitialCondition –> Initial Condition.
- kind (not editable)
Initial Condition
- expression
The value of the initial condition. Can be assigned a Constant, Parameter, or SpaceTimeFunction by right-clicking.
- component
Can be 0, 1 or 2 for the first, second, or third component of the field.
Field Boundary Conditions¶
To add a Boundary Condition, right-click on FieldBoundaryConditions and select your choice from Add FieldBoundaryCondition. Your choices for dimensionality and field solver in the Basic Settings element will determine which Boundary Conditions are available to add to your simulation. If the simulation is set up as an electrostatic 2D simulation in cylindrical coordinates (R-Z plane) and if the simulation begins at r=0, then a flag called includeCylAxis (see Section Grid) is set to true. At r = 0, we have set the default field boundary condition to be Neumann with the electric field set to 0. Therefore, the only boundary conditions that need to be set in a 2D cylindrical electrostatic simulation are at RMAX, ZMIN, and ZMAX. If the simulation begins at r > 0, then the user will need to specify the field boundary condition at RMIN.
When working with partial electrostatic boundaries it is important to confirm that the entire boundary is set, and that no boundary conditions overlap. A periodic boundary counts as an electrostatic boundary condition. To help facilitate this, dirichlet full simulation boundary conditions are set first, followed by neumann full simulation boundary conditions. Next partial dirichlet boundary conditions are applied, followed by partial neumann boundary conditions. So if setting only 1 partial boundary condition against a full simulation boundary condition no special care needs to be taken. However if for example, a partial lower Y and partial lower Z boundary condition are both set, it is important to make sure that the two do not overlap by offsetting the bounds of one of them by one cell. An example of this is provided in the VSimPD example, PenningSource.
- Dirichlet
Use a Dirichlet boundary condition to set the value of the potential field, Phi, on the surface.
- value
The value of the boundary condition. Can be assigned a Constant, Parameter, SpaceTimeFunction, External Circuit by right-clicking.
- surface
The surface on which the Dirichlet boundary condition should be set.
- lower x
The lower x boundary of the simulation domain.
- lower y
The lower y boundary of the simulation domain.
- lower z
The lower z boundary of the simulation domain.
- upper x
The upper x boundary of the simulation domain.
- upper y
The upper y boundary of the simulation domain.
- upper z
The upper z boundary of the simulation domain.
- partial lower x
A Dirichlet boundary condition applied only to part of the lower x simulation boundary. The entire lower x boundary, as well as one guard cell above the boundary must be filled with a boundary condition. The lower coordinate is included in the simulation and the upper bound is exclusive. Also note that at the intersection of the Y or Z simulation boundary the first computational cell of the X boundary is included in the Y or Z simulation boundary condition.
- lower y coordinate
The inclusive lower y coordinate.
- upper y coordinate
The exclusive upper y coordinate.
- lower z coordinate
The inclusive lower z coordinate.
- upper z coordinate
The exclusive upper z coordinate.
- partial lower y
A Dirichlet boundary condition applied only to part of the lower y simulation boundary. The entire lower y boundary, as well as one guard cell above must be filled with a boundary condition. The lower coordinate is included in the simulation and the upper bound is exclusive. Also note that at the intersection of the X or Z simulation boundary the first computational cell of the Y boundary is included in the X or Z simulation boundary condition.
- lower x coordinate
The inclusive lower x coordinate.
- upper x coordinate
The exclusive upper x coordinate.
- lower z coordinate
The inclusive lower z coordinate.
- upper z coordinate
The exclusive upper z coordinate.
- partial lower z
A Dirichlet boundary condition applied only to part of the lower z simulation boundary. The entire lower z boundary, as well as one guard cell above must be filled with a boundary condition. The lower coordinate is included in the simulation and the upper bound is exclusive. Also note that at the intersection of the X or Y simulation boundary the first computational cell of the Z boundary is included in the X or Y simulation boundary condition.
- lower x coordinate
The inclusive lower x coordinate.
- upper x coordinate
The exclusive upper x coordinate.
- lower y coordinate
The inclusive lower y coordinate.
- upper y coordinate
The exclusive upper y coordinate.
- partial upper x
A Dirichlet boundary condition applied only to part of the upper x simulation boundary. The entire upper x boundary, as well as one guard cell above must be filled with a boundary condition. The lower coordinate is included in the simulation and the upper bound is exclusive. Also note that at the intersection of the Y or Z simulation boundary the first computational cell of the X boundary is included in the Y or Z simulation boundary condition.
- lower y coordinate
The inclusive lower y coordinate.
- upper y coordinate
The exclusive upper y coordinate.
- lower z coordinate
The inclusive lower z coordinate.
- upper z coordinate
The exclusive upper z coordinate.
- partial upper y
A Dirichlet boundary condition applied only to part of the upper y simulation boundary. The entire upper y boundary, as well as one guard cell above must be filled with a boundary condition. The lower coordinate is included in the simulation and the upper bound is exclusive. Also note that at the intersection of the X or Z simulation boundary the first computational cell of the Y boundary is included in the X or Z simulation boundary condition.
- lower x coordinate
The inclusive lower x coordinate.
- upper x coordinate
The exclusive upper x coordinate.
- lower z coordinate
The inclusive lower z coordinate.
- upper z coordinate
The exclusive upper z coordinate.
- partial upper z
A Dirichlet boundary condition applied only to part of the upper z simulation boundary. The entire upper z boundary, as well as one guard cell above must be filled with a boundary condition. The lower coordinate is included in the simulation and the upper bound is exclusive. Also note that at the intersection of the X or Y simulation boundary the first computational cell of the Z boundary is included in the X or Y simulation boundary condition.
- lower x coordinate
The inclusive lower x coordinate.
- upper x coordinate
The exclusive upper x coordinate.
- lower y coordinate
The inclusive lower y coordinate.
- upper y coordinate
The exclusive upper y coordinate.
- shape surface
Use a shape surface to specify a Dirichlet boundary condition on the surface of a geometry in your simulation.
- object name:
Choose from any pre-defined geometries in the simulation.
- Neumann
Use a Neumann boundary condition to set the value of the derivative of the potential field, Phi, on the surface.
- value
The value of the derivative. Can be assigned a Constant, Parameter, or SpaceTimeFunction by right-clicking.
- surface
The surface on which the Dirichlet boundary condition should be set.
- lower x
The lower x boundary of the simulation domain.
- lower y
The lower y boundary of the simulation domain.
- lower z
The lower z boundary of the simulation domain.
- upper x
The upper x boundary of the simulation domain.
- upper y
The upper y boundary of the simulation domain.
- upper z
The upper z boundary of the simulation domain.
- partial lower x
A Neumann boundary condition applied only to part of the lower x simulation boundary. The entire lower x boundary must be filled with a boundary condition. The lower coordinate is included in the simulation and the upper bound is exclusive. Also note that at the intersection of the Y or Z simulation boundary the first computational cell of the X boundary is included in the Y or Z simulation boundary condition.
- lower y coordinate
The inclusive lower y coordinate.
- upper y coordinate
The exclusive upper y coordinate.
- lower z coordinate
The inclusive lower z coordinate.
- upper z coordinate
The exclusive upper z coordinate.
- partial lower y
A Neumann boundary condition applied only to part of the lower y simulation boundary. The entire lower y boundary must be filled with a boundary condition. The lower coordinate is included in the simulation and the upper bound is exclusive. Also note that at the intersection of the X or Z simulation boundary the first computational cell of the Y boundary is included in the X or Z simulation boundary condition.
- lower x coordinate
The inclusive lower x coordinate.
- upper x coordinate
The exclusive upper x coordinate.
- lower z coordinate
The inclusive lower z coordinate.
- upper z coordinate
The exclusive upper z coordinate.
- partial lower z
A Neumann boundary condition applied only to part of the lower z simulation boundary. The entire lower z boundary must be filled with a boundary condition. The lower coordinate is included in the simulation and the upper bound is exclusive. Also note that at the intersection of the X or Y simulation boundary the first computational cell of the Z boundary is included in the X or Y simulation boundary condition.
- lower x coordinate
The inclusive lower x coordinate.
- upper x coordinate
The exclusive upper x coordinate.
- lower y coordinate
The inclusive lower y coordinate.
- upper y coordinate
The exclusive upper y coordinate.
- partial upper x
A Neumann boundary condition applied only to part of the upper x simulation boundary. The entire upper x boundary must be filled with a boundary condition. The lower coordinate is included in the simulation and the upper bound is exclusive. Also note that at the intersection of the Y or Z simulation boundary the first computational cell of the X boundary is included in the Y or Z simulation boundary condition.
- lower y coordinate
The inclusive lower y coordinate.
- upper y coordinate
The exclusive upper y coordinate.
- lower z coordinate
The inclusive lower z coordinate.
- upper z coordinate
The exclusive upper z coordinate.
- partial upper y
A Neumann boundary condition applied only to part of the upper y simulation boundary. The entire upper y boundary must be filled with a boundary condition. The lower coordinate is included in the simulation and the upper bound is exclusive. Also note that at the intersection of the X or Z simulation boundary the first computational cell of the Y boundary is included in the X or Z simulation boundary condition.
- lower x coordinate
The inclusive lower x coordinate.
- upper x coordinate
The exclusive upper x coordinate.
- lower z coordinate
The inclusive lower z coordinate.
- upper z coordinate
The exclusive upper z coordinate.
- partial upper z
A Neumann boundary condition applied only to part of the upper z simulation boundary. The entire upper z boundary must be filled with a boundary condition. The lower coordinate is included in the simulation and the upper bound is exclusive. Also note that at the intersection of the X or Y simulation boundary the first computational cell of the Z boundary is included in the X or Y simulation boundary condition.
- lower x coordinate
The inclusive lower x coordinate.
- upper x coordinate
The exclusive upper x coordinate.
- lower y coordinate
The inclusive lower y coordinate.
- upper y coordinate
The exclusive upper y coordinate.
PoissonSolver¶
- kind (not editable)
Poisson Solver
- relative permittivity
Function giving the relative permittivity, or background permittivity. Without a VSimPD license, when using the electrostatic field solve, dielectrics with spatially dependent dielectric constants cannot be added through the use of geometries (primitive and CAD-like imported objects). If you try to add a non-PEC/Absorbium material, you will get the following error: “Dielectrics not supported in electrostatic simulations”. However, you can add regions in the simulation domain that have spatially dependent dielectric constants with SpaceTimeFunctions (see SpaceTimeFunctions).
An example demonstrating how to add dielectrics using SpaceTimeFunctions can be found in “Dielectric in Electrostatics” which can be found in the “VsimExamples” documentation. Once you have written a SpaceTimeFunction describing the spatially dependent dielectric constant, expand the Field Dynamics tab and left click on “PoissonSolver”. Then right click on the region next to relative permittivity, left click on “Assign SpaceTimeFunction” and click on the function that you wrote. With a VSimPD license it is possible to use geometry defined dielctrics. In this case the relative permittivity assignment can still be used to set a background permittivity, or permittivity outside of the geometries.
- solver
VSim allows the use of the direct solver SuperLU or one of the current choices for iterative solvers.
- SuperLU
Use the SuperLU solver. This is a direct matrix solver which is not recommended for use in a simulation with a grid larger than a few thousand cells. For grids with more than a few thousand cells, use an iterative solver.
- conjugate gradient
An iterative solver for symmetric positive definite matrices.
- tolerance
The size of the error vector for stopping the iteration to solution.
- max iterations
The maximum number of iterations allowed to achieve the solution. Anything above 30 is questionable.
- convergence metric
This is described in the AztecOO user guide, p. 17, currently here. Metrics are one of:
- r0
Use the ratio of the L2 norms of the residual and the initial residual.
- rhs
Use the ratio of the L2 norms of the residual and the right-hand side.
- Anorm
Use the ratio of the L2 norm of the residual and the maximum absolute row sum of the matrix (L-infinity norm).
- noscaled
Use the ratio of the L2 norm of the residual.
- sol
Use the ratio of the maximum component of the residual and the sum of (L-infinity norm of the matrix times the maximum absolute component of the first iterate to the solution + the maximum absolute component of the right-hand side).
- generalized minimum residual
An iterative solver. Actually the restarted GMRES. A very robust solver.
- Krylov vector space size
Number of vectors used in Krylov subspace.
- max iterations
The maximum number of iterations allowed to achieve the solution. Anything above 30 is questionable.
- tolerance
The size of the error vector for stopping the iteration to solution.
- convergence metric
This is described in the AztecOO user guide, p. 17, currently here. Metrics are one of:
- r0
Use the ratio of the L2 norms of the residual and the initial residual.
- rhs
Use the ratio of the L2 norms of the residual and the right-hand side.
- Anorm
Use the ratio of the L2 norm of the residual and the maximum absolute row sum of the matrix (L-infinity norm).
- noscaled
Use the ratio of the L2 norm of the residual.
- sol
Use the ratio of the maximum component of the residual and the sum of (L-infinity norm of the matrix times the maximum absolute component of the first iterate to the solution + the maximum absolute component of the right-hand side).
- orthogonalization
How to orthogonalize the Krylov subspace. Options are:
- classic
Uses two steps of the classical Gram-Schmidt orthogonalization (Default).
- modified
Uses one step of the Modified Gram-Schmidt orthogonalization.
conjugate gradient squared
- tolerance
The size of the error vector for stopping the iteration to solution.
- max iterations
The maximum number of iterations allowed to achieve the solution. Anything above 30 is questionable.
- convergence metric
This is described in the AztecOO user guide, p. 17, currently here. Metrics are one of:
- r0
Use the ratio of the L2 norms of the residual and the initial residual.
- rhs
Use the ratio of the L2 norms of the residual and the right-hand side.
- Anorm
Use the ratio of the L2 norm of the residual and the maximum absolute row sum of the matrix (L-infinity norm).
- noscaled
Use the ratio of the L2 norm of the residual.
- sol
Use the ratio of the maximum component of the residual and the sum of (L-infinity norm of the matrix times the maximum absolute component of the first iterate to the solution + the maximum absolute component of the right-hand side).
biconjugate gradient stabilized
- tolerance
The size of the error vector for stopping the iteration to solution.
- max iterations
The maximum number of iterations allowed to achieve the solution. Anything above 30 is questionable.
- convergence metric
This is described in the AztecOO user guide, p. 17, currently here. Metrics are one of:
- r0
Use the ratio of the L2 norms of the residual and the initial residual.
- rhs
Use the ratio of the L2 norms of the residual and the right-hand side.
- Anorm
Use the ratio of the L2 norm of the residual and the maximum absolute row sum of the matrix (L-infinity norm).
- noscaled
Use the ratio of the L2 norm of the residual.
- sol
Use the ratio of the maximum component of the residual and the sum of (L-infinity norm of the matrix times the maximum absolute component of the first iterate to the solution + the maximum absolute component of the right-hand side).
transpose-free quasi-minimal residual
- tolerance
The size of the error vector for stopping the iteration to solution.
- max iterations
The maximum number of iterations allowed to achieve the solution. Anything above 30 is questionable.
- convergence metric
This is described in the AztecOO user guide, p. 17, currently here. Metrics are one of:
- r0
Use the ratio of the L2 norms of the residual and the initial residual.
- rhs
Use the ratio of the L2 norms of the residual and the right-hand side.
- Anorm
Use the ratio of the L2 norm of the residual and the maximum absolute row sum of the matrix (L-infinity norm).
- noscaled
Use the ratio of the L2 norm of the residual.
- sol
Use the ratio of the maximum component of the residual and the sum of (L-infinity norm of the matrix times the maximum absolute component of the first iterate to the solution + the maximum absolute component of the right-hand side).
preconditioner
no preconditioner
- multigrid
Multigrid has a large number of parameters. In most cases, the defaults are good. If one is using particles, the linear solve often does not matter in overall timing. More information is available in the VSim User Guide: VSim User Guide: Simulation Concepts: Fields
mg defaults
- SA
Works best with symmetric matrices. Symmetric matrices occur when all boundary conditions in the problem are periodic.
- DD
Works best in general.
DD-ML
Maxwell
- maximum levels
The maximum number of levels of multigrid smoother application before doing a direct solve on the smaller problem. For highly parallel problems this should be limited to 3-4 to minimize communication time.
- smoother type
The smoother to apply at each multigrid level. The default is a good choice, but the user may try other smoothers to achieve best solving times. The choices are:
Gauss Seidel
symmetric variable block Gauss Seidel
Jacobi
Chebyshev
Aztec
- smoother sweeps
The number of times to apply the smoother at each multigrid level. A good choice is 3, but the user may try other values to achieve best solving times.
- when to smooth
Generally one wants to smooth both. The before and after choices are provided to the user to try other values to achieve best solving times.
both
before
after
- coarse type
The type of solver to use at the coarsest level.
Jacobi
KLU
- damping factor
Damping factor for smoothed aggregation. The default is a good choice. Users may try other values to achieve best solving times.
- threshold
This determines the multigrid aggregation at each level.
- increase or decrease
If set to increasing, level 0 will correspond to the finest level. If set to decreasing, max levels - 1 will correspond to the finest level. Should not affect convergence. The choices are:
increasing
decreasing