Setup Window for Visual-setup Simulations

After you open a new or example simulation that is not text-based, VSimComposer displays the Setup window containing a Editor pane with a Simulation Elements Tree, a Property Editor, and a Geometry View to allow for easy creation of your simulation. The icon panel remains available on the far left.

Note

A Navigation Pane can be shown by clicking and dragging on the vertical bar separating the Icon panel from the Editor pane. See Fig. 44.

Navigation Pane

Fig. 44 The Navigation Pane

The following sections will go through each of the components of the Setup window.

For in depth information on each of the properties and possible values outlined or described in the rest of the chapter, please see VSim Reference: VSimComposer.

The figure Visual based setup window illustrates the layout of the VSimComposer Setup window using labels for the parts of the interface to which this introduction and the tutorials refer. See Fig. 45.

Setup  Window

Fig. 45 Visual based setup window

Elements Tree

You can navigate through the Elements Tree using either your mouse, or your keyboard arrows. The up and down arrows will scroll up and down through the list of elements, while the right and left arrows will respectively expand and collapse the elements. To double click, press F2.

Highlighting a particular element in the tree will cause the Property Editor to update with Property/Value pairs that can be edited.

Description

The Description element holds basic user-supplied text information about the simulation.

Constants

The Constants element contains a set of pre-defined physical constants that can be used in other elements of the simulation. You may also define your own by highlighting Constants and either clicking the Add button at the lower right of the Elements Tree or right-clicking and selecting Add Constant –> User Defined.

The name of the user-defined Constant can be modified by double clicking on the element in the Elements Tree and typing in a new name.

Note

A constant name can contain only alphanumeric characters and underscore and must start with a letter. Our convention is to use ALL_CAPS for constants.

A value can be given to the user defined Constant by double clicking on the value in the Property Editor. See Fig. 46.

Constants

Fig. 46 Constant definitions

Parameters

The Parameters element is a location for evaluated, user-defined, variables that can be used in other elements of the simulation.

You can add a parameter by highlighting Parameters and either clicking the Add button at the lower right of the Elements Tree or right-clicking and selecting Add Parameter –> User Defined.

The name of the user-defined Parameter can be modified by double clicking on the element in the Elements Tree and typing in a new name.

Note

A parameter name can contain only alphanumeric characters and underscore and must start with a letter. Our convention is to use ALL_CAPS for parameters.

An expression can be given to the user defined Parameter by double clicking on the expression value in the Property Editor. You can use any of the Constants as well as any real number in the expression. See Fig. 47.

Note

If the expression is not valid, the parameter will appear in red in the Elements Tree.

Parameters

Fig. 47 Parameter definitions

Basic Settings

The Basic Settings element contains a group of property/value pairs that define the basic setup of the simulation.

Here you can find properties such as the type of field solve (electromagnetic or electrostatic), the dimensionality (3D, 2D, 1D), whether or not to include kinetic particles in the simulation, and the time step.

Functions

The Functions element is a location for writing user-defined functions that can be used in simplifying the definition of a SpaceTimeFunction. The function can contain any number of arbitrary arguments and is not limited to the default values of x and y.

Note

A Function can be used to define another Function or a SpaceTimeFunction. Functions cannot be used to define an expression in other elements nor can they be used to define parameters. Expressions are defined by SpaceTimeFunctions.

To create your own function, highlight Function and either click the Add button at the lower right of the Elements Tree or right-click and select Add Function –> User Defined.

The name of the user-defined Function can be modified by double clicking on the element in the Elements Tree and typing in a new name.

Note

A function name can contain only alphanumeric characters and underscore and must start with a letter. Our convention is to use lowerCamelCase for function names.

You can define the Function by double clicking on the expression value in the Property Editor. You can use any of the Constants, Parameters, or Functions previously defined, as well as any real number or Python operator in the expression. See Fig. 48.

Functions

Fig. 48 Function definitions

SpaceTimeFunctions

The SpaceTimeFunctions element is a location for writing user-defined functions that specifically depend on the spatial and temporal variables x, y, z, and t. A SpaceTimeFunction can be used in other elements of the simulation by right clicking on the value and selecting the defined SpaceTimeFunction as shown in the figure SpaceTimeFunctions definitions.

To create your own function, highlight SpaceTimeFunction and either click the Add button at the lower right of the Elements Tree or right-click and select Add SpaceTimeFunction –> User Defined.

The name of the user-defined SpaceTimeFunction can be modified by double clicking on the element in the Elements Tree and typing in a new name.

Note

A SpaceTimeFunction name can contain only alphanumeric characters and underscore and must start with a letter. Our convention is to use lowerCamelCase for SpaceTimeFunction names.

You can define the SpaceTimeFunction by double clicking on the expression value in the Property Editor. You can use any of the Constants, Parameters, or Functions defined above, as well as any real number or Python operator in the expression. See Fig. 49.

SpaceTime Functions

Fig. 49 SpaceTimeFunctions definitions

Materials

The Materials element holds information about any materials used in the simulation. There are some Materials built into VSim, and the user may import other desired materials.

To import a Material, either click the Add button at the lower right of the Elements Tree or right-click and select Import Materials.

The Materials file must have the extension .vmat. You can specify your own materials file to import special materials specific to your simulation. See Fig. 50.

Note

Tech-X has a standard materials file distributed with VSim. It is located in the data folder of your installation.

Materials

Fig. 50 Importing materials

Once a material file has been imported into VSimComposer, you can add a specific material to your simulation by highlighting the material of choice and clicking on the Add To Simulation button.

After a material is in the simulation, you can see it under the Materials element. The material properties can be modified, if desired. The Materials can be assigned to a geometry in the material property in the Properties Editor pane. See Fig. 51.

Materials Add

Fig. 51 Adding materials to the simulation.

Geometries

The Geometries element contains information about any geometries that are in the simulation. You can import a file, or create your own with CSG.

Expanding the Geometries sub-elements view will show the individual parts (if any) of the imported geometry, or CSG built geometry.

To hide a specific part, uncheck the box next to it.

Note

Hiding a part of the geometry will not remove it from the simulation. VSim will use the full geometry defined in the imported file.

For use in the simulation, a Geometries part MUST have a material assigned to it, other wise it is ignored (treated as vacuum).

The material can be assigned to a geometry by double clicking on the material value in the Properties Editor.

Import a Pre-defined Geometry

To import a geometry into your simuation, highlight the Geometries element in the Elements Tree and click on the Add –> Import Geometries button located at the bottom of the Elements Tree, or simply right click on the Geometries element –> Import Geometries.

Here you can navigate to a supported file type and open the file. Supported filed types include:

  • Step Files (.stp, .step, .p12)
  • STereoLithography Files (.stl)
  • Visualization Toolkit Files (.vtk)
  • Polygon File Format (.ply)

Build Your Own Geometry

You can build your own geometry using Constructive Solid Geometry (CSG) to create a complex shape by combining simple shapes using boolean operators.

To do this, highlight the CSG element and right click Add Primitive and select one of the pre-defined shapes. See Fig. 52.

Constructive Solid Geometry

Fig. 52 Constructive Solid Geometry (CSG)

After multiple CSG shapes have been added, you can either subtract, union, or intersect them with a boolean operation. This will create a new Geometries element.

To do this, highlight a maximum of 2 shapes, right click, and select the boolean operation you want. See Fig. 53.

Note

The order of highlighting your shapes matters when doing the subtract boolean operation. The second shape will be subtracted from the first. The boolean operation menu will show the operation to be performed based on the order of highlighting.

Constructive Solid Geometry Boolean Operator

Fig. 53 Constructive Solid Geometry (CSG) Boolean Operator

Note

If a shape is not part of a combined shape through a boolean operation, you can assign a material to it. Once a shape has been combined with another shape, only the combined shape may be assigned a material.

Grids

The type of grid is determined in the Basic Settings element. Its parameters are determined in the Grid element.

By default, a uniform Cartesian grid is added to your simulation with dimensions of 1m x 1m x 1m and cell numbers of 3, 4, and 5 in x, y, and z respectively.

To modify the type of grid, change the Basic Settings properties coordinate system, dimensionality, and grid spacing. See Fig. 54.

Grid Choices

Fig. 54 Grid choices

The size of the domain can be set using the Min and Max properties of the Grid element. The number of cells in each direction can also be specified. See Fig. 55.

Note

Only one grid may be added to any one simulation at a time.

Grids

Fig. 55 Grid settings

Note

A grid can be resized to fit the bounds of a geometry by right clicking on the Grid element and choosing Resize Grid. Resizing the grid puts in numbers. Any constants and parameters are lost.

Field Dynamics

The type of field solver is determined in the Basic Settings element. Its parameters are specified in the Field Dynamics element.

Fields

Depending on the type of solver chosen, default fields will be initialized in the simulation. For an electrostatic simulation, default fields will be Phi, Charge Density and Electric Field. You can optionally add a Background Charge Density field or External Field by clicking the Add –> Add Field button located at the bottom of the Elements Tree, or simply right clicking on the Fields element –> Add Field.

An External Field is used for importing a Magnetic field in electrostatic simulations with particles.

For an electromagetic simulation, default fields will be Electric Field and Magnetic Field. You can optionally add a Current Density field or External Field by clicking the Add –> Add Field button located at the bottom of the Elements Tree, or simply right clicking on the Fields element –> Add Field.

An External Field in electromagetic simulations can be a Magnetic, Electric, or Current field. External fields are used to effect particle movements in simulations.

Field Initial Conditions

An initial condition can be added to any field by clicking the Add –> Add FieldInitialCondition button located at the bottom of the Elements Tree, or simply right clicking on the particular Field element –> Add FieldInitialCondition. See Fig. 56.

field initial condition

Fig. 56 Adding an initial condition to a field

Field Boundary Conditions

A boundary condition can be added to any field by clicking the Add –> Add FieldBoundaryCondition button located at the bottom of the Elements Tree, or simply right clicking on the particular Field element –> Add FieldBoundaryCondition.

Current Distributions

A current distribution can be added to any field by clicking the Add –> Add CurrentDistribution button located at the bottom of the Elements Tree, or simply right clicking on the particular Field element –> Add CurrentDistribution.

A distributedCurrent is a volume current source where you can provide the min and max values in each direction. A distributedCurrent will show up on the Geometry View. You can hide a distributedCurrent by unchecking the box next to it. Hiding a current will not remove it from the simulation, it’ll just hide it from the geometry view. See Fig. 57.

distributed current

Fig. 57 A volume of current is shown in the smaller/interior box. The outer box is the grid.

Poisson Solver

The type of Poisson solve and any preconditioner can be set under the solver and preconditioner properties of the Properties Editor.

Note

Changing the solver type may introduce more properties due to the context-sensitive nature of the input.

Particle Dynamics

The inclusion of Particle Dynamics is determined by the value of particles in the Basic Settings element. If particles is set to no particles, then no particles are in the simulation and the Particle Dynamics element is hidden.

If particles is set to include particles then the Particle Dynamics element is shown and futher properties can be set.

The Particle Dynamics element holds information on any kinetic particles, background gases, and collisions in the simulation.

KineticParticles

Electrons, charged particles, and neutral particles can be added to the KineticParticles element.

To add kinetic particles, click the Add –> KineticParticle button located at the bottom of the Elements Tree, or simply right click on the KineticParticles element and select Add KineticParticle and then choose the type of particle you want to include.

The properties of each kind of KineticParticle are modifiable in the Properties Editor pane.

BackgroundGases

To add collisions between types of kinetic particles, click the Add –> Add BackgroundGas button located at the bottom of the Elements Tree, or simply right click on the BackgroundGases element and select Add BackgroundGas.

A backgroundGas is a volume distribution where you can provide the min and max values in each direction. A backgroundGas will show up on the Geometry View. You can hide a backgroundGas by unchecking the box next to it. Hiding a the backgroundGas will not remove it from the simulation, just hide it from the geometry view. See Fig. 58.

background gas

Fig. 58 A volume of gas is shown in the smaller/interior box. The outer box is the grid.

Collisions

There are three frameworks for setting up particle collisions available in VSim. The newest, most flexible, and fastest is the Reactions framework. The Reactions framework supplants the Monte Carlo Interactions framework. The Impact Collider (called “ReducedCollisions” in the Visual Setup) framework is the oldest framework, and is limited to interactions between kinetic particles with a neutral background gas, but runs very quickly.

In the Visual Setup, only one framework can be used at a time.

Reactions

To include Reactions in the Visual Setup, first select the Basic Settings element of the setup tree and ensure that the particles dropdown menu is set to “include particles” and the collisions framework dropdown is set to “reactions.”

With these settings selected, collisions can now be set up within the Particle Dynamics element of the setup tree. The Reactions are organized between five options: Particle Particle Collisions, Particle Fluid Collisions, Three Body Reactions, Field Ionization Processes, and Decay Processes. By highlighting one of these five options, right clicking, and adding a collision process a user is setting a RxnProductGenerator`(see :ref:`VSim Reference Manual: Text Setup: Reactions <rxn-rxnProductGenerator> for more information on RxnProductGenerators).

Note

The distinction between the Particle Particle Collisions and Particle Fluid Collisions is artificial in the visual setup and is made for the convenience of the user.

After adding a collision process to the tree, the user then selects the reacting species, cross-sections/reaction rates, and other reaction attributes. The species and fluids in the drop down menu for reactants and products are limited such that only selections appropriate for the process are available. Charge and mass conservation is checked during the translation from .sdf to .in. If there is a charge or mass violation, an error will be thrown.

If the drop-down menu used to set the interacting particle species is empty, make sure you’ve added the necessary KineticParticle or BackgroundGas for the type of collision.

Reduced Collisions (Impact Collider)

To include Reduced Collisions in the Visual Setup, first select the Basic Settings element of the setup tree and ensure that the particles dropdown menu is set to “include particles” and the collisions framework dropdown is set to “reduced”. With these settings selected, collisions can now be set up within the Particle Dynamics element of the setup tree.

To add collisions between kinetic particles and a neutral background gas (fluid), click the Add –> Add ParticleFluidCollision button located at the bottom of the Elements Tree, or simply right click on the Collisions element and select Add ParticleFluidCollision and choose whether either Electron Neutral Fluid Collision or Ion Neutral Fluid Collision. After making a selection, a new element will appear in the tree. Choose the particle species and the background gas that will interact.

To add a specific collision process, highlight this new element and choose a specific collision process from the Add CollisionProcess menu which will appear next to the mouse arrow. When a specific collision process is added, a new element will appear. The cross-sections for the interaction process will be set in this element.

See Fig. 59 for an example of adding collisions to a simulation in the Visual Setup.

Collisions

Fig. 59 Collisions

Monte Carlo Interactions

To include Monte Carlo Interactions in the Visual Setup, first select the Basic Settings element of the setup tree and ensure that the particles dropdown menu is set to “include particles” and the collisions framework dropdown is set to “monte carlo”.

With these settings selected, collisions can now be set up within the Particle Dynamics element of the setup tree. The Monte Carlo are organized between five options: Particle Particle Collisions, Particle Fluid Collisions, Three Body Reactions, Field Ionization Processes, and Decay Processes. The user can add a specific interaction process by highlighting one of these five options, right clicking, and selecting a process from the Add CollisionType menu.

After adding a collision process to the tree, the user then selects the reacting species, cross-sections/reaction rates, and other reaction attributes.

Histories

Histories are used to calculate and record data about fields and particles in a simulation.

ArrayHistory

An Array History will output an array of data for each time-step.

Note

This type of history is not currently viewable in VSimComposer.

Possible Array Histories include:

  • Far-Field Observation
  • Particle Momentum

ComboHistory

Combo Histories are used to do operations on other histories. The operation is done at every time step and the resulting values are recorded as a new history. The output will be a 1D array of the value vs time.

Possible Combo Histories include:

  • Binary Combination History

FieldHistory

Field Histories record on a per time-step basis. Field histories are used to measure quantities such as the value or energy of the field at a location. The output will be a 1D array of the value vs time.

Possible Field Histories include:

  • Electric Field Energy
  • EM Field Energy
  • Magnetic Field Energy
  • Field at Position
  • Poynting Vector
  • Pseudo-potential

LogHistory

A Log History will record data on a per-event basis rather than at each time step. For instance, an Absorbed Particle Log will record information about each and every particle that strikes a chosen absorbing surface. The output will be a 1D array of the value.

Possible Log Histories include:

  • Absorbed Particle Log

ParticleHistory

Particle Histories record on a per time-step basis. Particle histories are used to measure quantities such as the total number of particles in a simulation at each step, or the current absorbed at a chosen absorbing surface at each step. The output will be a 1D array of the value vs time.

Possible Particle Histories include:

  • Absorbed Particle Current
  • Absorbed Particle Energy
  • Emitted Current
  • Number of Macroparticles
  • Number of Physical Particles
  • Particle Energy

Property Editor

The Property Editor allows for setting of specific properties under each of the Elements from the Elements Tree for the simulation. Such properties might include sizes in the X, Y, and Z directions, the type of particles, and specifics of a field solve.

The Property and Value inputs are context-sensitive. The availability of a particular property may depend on other properties or selections of the Element Tree. For instance, changing the solver value in the PoissonSolver element will bring up a new set of solver properties to be set. Refer to the figure Constructive Solid Geometry (CSG) Boolean Operator (Fig. 53) to see the same principle with regard to geometry options.

Geometry View

The 3D View section can be used to view the simulation setup including the geometry, grid, and source.

Buttons

  • Properties

  • View Solids

  • Select Solid

  • Toggle Axes

    A toggle button to show or hide the axes.

  • Perspective View

  • Axis Drop-down Menu

    Drop-down menu for choosing the axis from which the object is viewed.

  • Reset Position

    Pressing this button will reset the camera view to be along the axis selected in the drop-down menu.

Database View

The Database View is for viewing and adding materials to your simulation. Initially, the Database View is blank, but upon importing a materials (.vmat) file, the view is populated with a table of data from the file. See Fig. 60.

Database view

Fig. 60 The Database view

You can switch between files, if more than one file is open, by changing the left drop-down menu. You can remove a file by first switching to the file you would like to close, and then clicking on the Remove File button.

You can add materials to your simulation by highlighting the particular material you are interested in, and then clicking on the Add to Simulation button.

For more information on materials, please see Materials.