VSim User Guide

VSim User Guide


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.

What is VSimComposer?

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.


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 Capabilities

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.

Starting VSimComposer

Running Locally

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.

Running VSim on Windows

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.


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”.

Running VSim on Mac

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

Running VSim on Linux

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.

Running VSimComposer On a Remote Computer System

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:


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.


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.

Visualizing Remote Data

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.

Welcome Window

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.

Creating or Opening a Simulation

Starting a Simulation

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.

Creating a Simulation from an Example

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.

    Fig. 7 Create new simulation from example
Select Example Template

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.

Fig. 8 Selecting an example from the Examples dialog

Choose a Name for the New Simulation

Upon selection of the example template, the window Choose a Simulation Name will open. Here you can choose the folder, or create a new folder, and set the name of the new simulation.

When the name and directory have both been chosen, click the Save button to proceed. See Fig. 9.

Fig. 9 Choose name and directory to use for the simulation
Proceed to the Setup Window
From here, Composer will automatically take you to the Setup window where you are free to explore and alter the parameters of the example you have chosen. See Fig. 10.

Fig. 10 Proceed to the setup window

Opening an Existing Simulation

If you have a simulation already created, you can double-click on the simulation .sdf or .pre file that appears under Recent Simulations in the VSim Composer Welcome menu.

Or, if your simulation does not show under the Recent Simulations heading, you can go to File -> Open Simulation and use the Open Simulation file navigation window to select the simulation .sdf or .pre file you would like to open. See Fig. 11.

Fig. 11 Open an existing simulation .sdf or .pre file

Creating a Blank Simulation

Create New Visual Setup Simulation

To create a completely custom visual-based simulation, you must choose New -> Simulation from the File menu. Creating an entirely new simulation requires knowledge of topics covered in later sections. See Fig. 12.

Fig. 12 Choose to create a new visual setup simulation