This manual demonstrates how to use either the Visual Setup (.sdf input files) or Text Base Setup (.pre input files) to set up a VSim simulation. It then shows how to run the computational engine on the resulting input files, how to perform data analysis in VSim, and how to visualize data.
VSim [VSi] is an arbitrary dimensional, electromagnetics and plasma simulation code consisting of two major components:
VSimComposer, the graphical user interface.
Vorpal [NC04], the VSim Computational Engine.
VSim also includes many more items such as Python, MPI, data analyzers, and a set of input simplifying macros.
VSimComposer provides an interface that allows you to edit and validate your simulation input files, run VSim simulations, and visualize results using the VisIt-based Visualization pane embedded within VSimComposer. You can also edit VSim input files in the text editor of your choice, perform calculations with the easy-to-run, command-line-driven Vorpal engine, and then run the visualization tool of your choice.
Note
Look and Feel Differences
VSim runs on Linux, Mac OS X, and Windows. Each of these platforms has its own unique look and feel (e.g. the ordering of buttons in dialogs, and in the case of Mac OS X the arrangement of menus and menu items). Furthermore, the appearance of VSim can vary depending on the theme being used.
Given these differences and that screenshots may not always be of the most recent release, please note that screenshots shown in this manual may look different from the VSim that you see running on your own computers. VSim should function the same, but if you look for a particular toolbar or button, it may not be in same place in your copy of VSim.
VSim is a flexible, multiplatform, high-performance tool for running electromagnetic, electrostatic, and plasma simulations in 1, 2, or 3 dimensions.
VSim solves EM propagation in the presence of complex dielectric and metallic shapes with accurate simulation of curved geometries using a conformal mesh. Examples include:
Dish Antenna
Horn Antenna
Patch Antenna
Waveguides
Far Field calculations
Radar Cross Sections
Crab Cavities
The kinetic plasma model is based on the particle-in-cell (PIC) algorithm, both in the electromagnetic and electrostatic limits. For electromagnetics, a charge-conserving current deposition algorithm enables the integration of the Maxwell equations without any additional divergence correction. In the electrostatic limit, the VSim computational engine (Vorpal) solves Poisson’s equation at every time step based on the instantaneous charge distribution. Examples include:
Magnetrons
Electron guns
Ion sources
Multipacting in waveguides
Traveling Wave Tubes
Hall Thrusters
Laser Plasma Accelerators
The structures within the VSim applications can be arbitrarily shaped and can define the locations of conductors, dielectrics, particle absorbers, reflectors, and other geometrical objects.
Once you have installed VSim successfully as per the instructions given by VSim Installation, you are ready to run the program. This section will detail how to run VSim locally on Windows, Mac, and Linux operating systems.
You can start VSim in the following ways on Windows:
Select the VSim Icon
Double-click on the VSim shortcut on your desktop
Go to your Start menu, navigate to the Tech-X folder, and click on the VSim icon
Run VSim from the Windows Command Line
Navigate to the relevant program folder by going to Program Files -> Tech-X -> VSim-10.0 -> Contents -> bin
Type in VSimComposer.exe to run the VSim executable and launch the program
Open VSim through Windows File Explorer
Open Windows File Explorer, either through your start menu, desktop shortcut, or taskbar icon
Navigate to C:Program FilesTech-XVSim-10.0
You can either click on the VSimComposer.lnk shortcut in this folder, or…
Continue on to Contents –> bin and then double-click on VSimComposer.exe
Open VSim using an existing file
Open Windows File Explorer
Select a file that has a VSim-supported extension (like a .pre, .in, or .sdf, for example). Either…
Double-click on the file if its default program is VSimComposer
If its default program is not VSimComposer, right-click on the file and select Open with. Go into Program Files -> Tech-X -> VSim-10.0 -> Contents –> bin and select the VSimComposer.exe application file.
Note
There is a known Windows-OpenGL issue when using VSim over a Microsoft Remote Desktop connection where the application window appears blank on some Windows machines with some graphics cards or some drivers. We provide a RemoteVSimComposer.bat script to work around this issue. It disconnects the remote session and starts VSim while disconnected, so that when the user reconnects, VSim works properly. If you see this issue, launch this script by right-clicking on RemoteVSimComposer.bat and choose “Run as administrator”.
On Mac OS, the methods for starting VSim are:
Start from the Applications Folder
Click on the VSimComposer icon in the Applications/VSim-10.0 folder (or in the folder where you have VSim installed)
Run VSim from Terminal Window
Open a Terminal window
Navigate to the folder where VSimComposer is installed, most likely by going to /Applications/VSim-10.0/VSimComposer.app/Contents/MacOS
Start VSim by typing ./VSimComposer.sh to run the program executable
For Linux, you can start VSim through the following:
Navigate to the folder where the program is installed, for example /user/local/VSim-10.0-Linux64
Type in ./VSimComposer.sh to run the program executable.
Just as on a local workstation or laptop, the computational engine (Vorpal) may be invoked through the graphical interface or from the command line on a remote system. On high performance computing clusters the command line approach may be required in order to submit a job to a resource management system. These are documented separtely here: - Running Vorpal from the Command Line - Running Vorpal from a Queueing System
In this section we discuss alternatives for setting up, running via the GUI, and visualising output.
In the present version we offer the following capabilities for running VSim remotely:
Note
Prior to starting up VSim, it may be necessary to set the environment variable export LIBGL_ALWAYS_INDIRECT=1
in order for the visualization stage to work correctly.
Note
Some users using VNC on ubuntu 14.04 have also reported adding the system installation of mesa to the start of the LD_LIBRARY_PATH environment variable, has helped overcome their issues. export LD_LIBRARY_PATH=/usr/lib/x86_64-linux-gnu/mesa:$LD_LIBRARY_PATH
Remote Desktop: We have tested two different methods for setting up a remote desktop on a server. One method uses VNC such as Tight VNC and Turbo VNC. If a VNC server is set up on the remote machine, one may try to connect a local client to the remote machine using VNC. Another method is through the use of NoMachine. In order to log in to a remote server, the same software needs to be installed on both the server and the client. Please work with your local support staff to ensure any one of these software solutions is correctly installed on both the server and client.
Virtual GL: If one is using a remote machine that has virtualGL server or DCV one may run using the hardware acceleration on the remote machine. This may provide the best performance but also the most system administration work. Many HPC centers are already set up for this kind of access. There is a super-accelerated virtualGL client, but it is more common to find virtualGL set up like DCV such that the remote machine is running a VNC server, which you may connect to with any VNC client on your local machine.
X Windows: If one does not have hardware acceleration on the remote machine one may forward X using an ssh client (ssh -Y
) or use accelerated X forwarding using software like NoMachine NX. As of this writing, a good discussion is at (https://www.hoffman2.idre.ucla.edu/access/x11_forwarding). Briefly,
Linux users running X: edit /usr/bin/Xorg as described at the above link.
OS X users running XQuartz: execute
defaults write org.macosforge.xquartz.X11 enable_iglx -bool true
Windows users: many options described at the above link. In addition, you can install an X server (such as XMing) on your Windows machine. You will also need to install Cygwin. Follow these steps to open Composer on a remote Linux machine. (1) Start the XMing server on your local computer. (2) Open Cygwin and type the following commands in the Cygwin terminal: - startxwin & - export DISPLAY=:0.0 - xterm & - ssh -XY address.to.your.remote.machine - navigate to location of installed VSim software and issue the command ./VSimComposer.sh
If X11 forwarding is enable on the remote machine, then this should open a Composer window.
The following capabilities are recommended for visualizing remote data if the previous recommendataions do not work for you:
One may use an external utility to copy the remote files back to a local machine (scp, sftp or winSCP are likely options). Providing the .pre or .sdf file is in the same directory as the data to be viewed, it should be possible to visualize the output locally. This is the most appropriate solution for those dealing with small datasets.
Use standalone VisIt and it’s remoting feature. VisIt may be downloaded from (https://wci.llnl.gov/simulation/computer-codes/visit/downloads). Users of native VisIt should be sure to make sure their local version number matches up with the version running remotely. This option offers the full flexibility of VisIt, such as the ability to make all the individual images needed to make movies in a single go and the ability to fully Python script your visualisation, but there is a corresponding learning curve. There are many tutorials and resources at The visitusers website (http://www.visitusers.org).
Use matplotlib or alternative software on the remote machine. The VsHdf5 module is provided with VSim and may be used to read and manipulate remote datasets for this purpose.
If you are using VNC or NoMachine, you can open any data set through Composer just as you would on your own desktop.
Upon opening VSim, you are brought to the Welcome Window. If it is your first time opening VSim, your Recent Simulations will be empty. However, if you have completed previous runs, you may use this area to quickly select a recent simulation and re-open it. You can also create new simulations based on those you have recently worked with. The Welcome Window is shown in Figure 6.
The first step to creating your own simulation is to open a file. It can be an existing example, an existing simulation, or a completely new simulation.
To run one of the examples in VSim, one must first copy the example file, and any correlated files, to a new directory. Choose New -> From Example from the File menu. See Fig. 7.
The Examples dialog box will open and you can choose an example template to run. Here a short description and image of the available examples will be displayed. Examples are split into VSim Modules. You must possess the correct license for an example to run, though you can see them all.
Upon selecting an example from the Available Templates pane, either double click the example you have chosen or single click and then click the Choose button.
For this demonstration we have chosen the Electromagnetic Plane Wave example from the VSim for Basic Physics module. See Fig. 8.