Chapter 5, Section 3 of User's Guide for CPO2D and CPO3D
Running the CPO programs.
Part 1:
The main headings in this section are (look for blue format):
Some important advice.
Step-by-step example.
Usual sequence of operations to run a CPO program.
Batch mode and command line running.
Windows (or boxes).
Moving boxes.
Tiling or recovering.
Position of ray tracing box.
Menu bar, with many comments, including:
Creating a solid object.
Loss of contour symmetry when zooming.
Moving windows.
Nonzoom
Contours.
Extra accuracy near electrodes.
Information displayed on the bottom bar.
Loss of part of picture or contours:
Information on other options is given in Part 2.
Some important advice:
Before explaining how to run the programs, here is some important advice:
The programs use data files and create various associated files, some of which can be very long (these end in .yyy). The available memory space in the computer can become overloaded if the old data and associated files are not occasionally deleted. It is also recommended that the memory should be occasionally defragmented using a ‘defrag’ icon.
The space-charge package contains CPO2DS, CPO3D and CPO3DS. For non-space-charge 3D simulations it is faster to use CPO3D, because CPO3DS always calculates the inverse matrix (which takes extra time). CPO2DS works in a slightly different way -the inverse matrix is only calculated when it is known that it will be needed.
Step-by-step example:
If you are a first-time user go to step-by-step example to see some of the operations.
Usual sequence of operations to run a CPO program:
After some experience has been gained the usual sequence of operations to run a CPO program is:
Click on File
Click on Open data builder file
Select (or type the name of) a data file
If you want to change the file, click on Databuilder and make the changes
Click on Run
The program then reads the information on the electrodes and segments, and calculates the surface charges. Information appears on the screen to keep the user informed about the various stages in the calculation.
In some of the files specific information is requested on potentials and electric fields, which therefore appears on the screen and is also put into the relevant output data file. This type of information, in this form, is useful for some users.
The electrode geometry will then appear on the screen and tracing of the rays will begin. The rays will be plotted on the screen as they evolve, and detailed numerical information will also appear in the 'Information' box. The same information is put into the output data file. This file can be accessed in various ways, for example from Notepad or DOS. Alternatively the same data from the Information box can be copied onto the clipboard, but it is necessary to CLOSE A RUN before copying into notepad, etc, or else some of the last lines might not be copied.
When the rays have finished, follow the prompts and explore what is available on all the various options described in below.
Batch mode and command line running:
For the more professional user:
It is possible to use command line running (in DOS mode or simulated DOS):
cpo3d temp.dat
where temp.dat is the name of the input data file (and where cpo3d can of course also be cpo3ds, cpo2d or cpo2ds). The program will then run with no pauses, and no opportunities to change the data or see the contours, etc. It will exit on completion, leaving information in the output data file.
This way of running is usually much faster than the conventional mode. The last view can be saved.
This way of running is also useful for the batch mode in which a succession of calls is put in the batch file. The ‘window’, not ‘full screen’ option should be used and the command lines should be
start /w cpo3d temp.dat
to prevent the calls from overlapping.
The views can be saved.
Information on pre-setting colours is given at the end of the note on colours.
Running a series of data files, in more detail:
(1) Set up the first data file, called temp1.dat, say.
(2) Copy it to another file, called temp2.dat, say, and make the necessary changes, using the databuilder or manually. These changes will typically involve changes to the geometry or ray tracing parameters. Do not forget to change the name of the ray output file.
(3) Repeat this for any further data files.
(4) Create a ‘.bat’ file, called tempb.bat, say.
(5) Put the following lines into the bat file (assuming that you are using CPO3D, otherwise change this to CPO2D, CPO3DS etc):
start /w cpo3d temp1.dat
start /w cpo3d temp2.dat
start /w cpo3d temp3.dat
…
(6) Activate the bat file either by double-clicking on its icon or by using the command line ‘tempb’.
(7) The data files will then automatically be run in sequence.
(See end of this note for information on what to do if parts of the picture or contours are lost.)
An extended version of command line running is available:
cpo3d temp.dat temp2.dat 1
Here extra data are put into the second named file, temp2.dat in this example. The type of information is governed by the integer at the end of the line. When it is 1 the data are the coordinates of the corners of the segments. Other options do not exist at present but can be added if users request this.
Windows (or boxes):
Two windows open up initially:
The window at the front (the graphics window) will show the electrodes and rays.
The window behind (the information window) will contain numerical information (and is a copy of the output data file).
A ‘Ray tracing’ box will open when the rays start, to show detailed step-by step information on the rays.
Further windows will be opened later, depending on the type of calculation and the information requested. For further information see note on screen layout and messages.
All the windows can be moved and nearly all of them can be expanded, contracted or deleted. Those that cannot be expanded in a single operation usually have sides that can be moved to effect an expansion. One advantage of minimising the graphics box (or hiding it with the edit or information boxes) is that the computing time for the ray tracing can be reduced (sometimes significantly).
Information also appears on the status bar at the bottom of the screen.
Moving boxes.
Tiling or recovering:
To 'tile' windows, or to recover hidden windows, click on Windows and then on Arrange.
Position of ray tracing box:
If the user wants to control the position of the Ray Tracing box then x and y coordinates should be entered at the beginning of the ‘comments’ for the last applied voltage -the preset values are 0.65 and 0.60 respectively. To put the box near the bottom right-hand corner of the screen, enter 0.85 0.8.
Warnings:
The two extra numbers cannot be added for time-dependent voltages because they will be mistaken for time parameters.
The two extra numbers can be added by using databuilder but you must remove them before saving the file -otherwise there will be an error message when the file is rerun.
Menu bar:
The details of the menu bar are give below, but before that here is a small fraction of the available menu and sub-menu items:
Menu item/Sub-menu item Action (if not obvious)
File/Open for running only Opens a new input data file (and closes any existing file)
File/Open for data-builder Needs name of an input data file, such as one of the ‘test’ or ‘example’ files supplied with the CPO package
File/Save (data-builder file) Saves with the same name
File/Save As (data-builder file) Saves with a new name
File/Open for manual editing Not recommended. This is a relic from the time when the databuilder was not available. See note on manual editing.
File/Copy to graphics clipboard Enables copying and pasting of the graphics window into a word processor or drawing program
Zoom/ The cursor is moved to the position of a corner of the required box and then the left-hand mouse button is pressed and kept pressed while the cursor is moved to the opposite corner. Pressing the right-hand mouse button gives a simple ×2 magnification without changing the aspect ratio. Look at the bottom bar for information.
Zoom/With aspect ratio 1 to 1 Either the vertical or horizontal size of the zoom box is increased to give this ratio
Contour/ Gives 2D contour plots of potentials or electric fields or (for 3D versions only) magnetic fields
2D/ Selects a two-dimensional view
3D/Rotate, shift, perspective, angle, scale Selects a three dimensional view (see second part of section 5.3).
View (2D and 3D)/Segments, rays, test planes Any of these can be removed
View (3D only)/ZX, XY, ZX The first letter denotes the horizontal axis on the screen and the second the vertical axis
View/Solid Creates a solid object by filling in all the segments, starting with those at the back -this option requires a longer plotting time (see second part of section 5.3).
View/Cut-away, illumination (see second part of section 5.3).
Window/ The windows can be moved and nearly all can be expanded or contracted (or else usually have sides that can be moved to effect a change in size). Minimizing the graphics window (or hiding it with the edit or information boxes) increases the tracing speed.
Window/Arrange To tile windows and hence recover hidden windows
(see second part of section 5.3).
Help/ Contains all that is in the Users Guide, the footnotes of the test and example files, detailed information on all the options and much else besides, giving a total of more than 800 pages all of which are easily accessible.
Help/Search Gives an alphabetical list of several hundred topics
(see second part of section 5.3).
The menu bar contains the following options, which are described in order.
File, Databuilder, Run, Zoom, Nonzoom, Contour, 2D, 3D, View, Voltages, Window, Palette and Help.
(except that 2D, 3D and Palette are not present for CPO2D)
Any item on the menu can be accessed by using the mouse to click on the name, and then clicking on any sub-menu items that appear. Alternatively you can type ALT plus the underlined letter. For example <ALT-F> will gain access to the File sub-menu, following which sub-menu items are reached quickly by typing the underlined letter only (no ALT is necessary at this stage). But beware that if the typing is carried out too quickly, before the menu items appear, then the program can crash (see notes on crashing).
The options File, Databuilder, Run, Zoom, Nonzoom, Contour are described here.
For descriptions of the options 2D, 3D, View, Voltages, Window and Help proceed to the second part of section 5.3.
(e
File contains the following sub-menu items:
Open for running only - Opens a new input data file, even if an existing file has been opened. It therefore closes any existing file automatically.
Close: - Closes the input data file.
Open data builder file - Needs name of an input data file, such as one of the test or example files supplied with the CPO package.
Close: - Closes the input data file.
Save (data builder file) - Saves with the same name.
Save As (data builder file) - Saves with a new name.
Copy to graphics clipboard: enables copying and pasting of the graphics window into a word processor or drawing program.
Print and Exit: require no explanation.
Databuilder: Opens the data-builder, with all its many options for changing data.
Run: This and all other options apart from Help are greyed out initially. The Run command is enabled after a file is opened successfully. Thereafter a file can be re-run, usually with different sets of voltages.
The 'Ray tracing' box that is open while the rays are being traced has information on the present coordinates, velocity components, etc, and also has the options Pause, Resume, Step, Stop. For detailed information on ray tracing and plotting see the note on rays.
Zoom: This option enables zooming of the 2D view currently selected (which is the zy view by default). A choice is given for the aspect ratio (that is, the ratio of the range of vertical to horizontal coordinates). For the choice with aspect ratio 1 to 1 either the vertical or horizontal size of the zoom box is increased to give this ratio, whereas for the choice without aspect ratio the zoom box is not altered. After making this choice the cursor should be moved to the position of a corner of the required box and then the left-hand mouse button should be pressed and kept pressed while the cursor is moved to the opposite corner.
Loss of contour symmetry when zooming:
An electrode system nearly always possesses some geometrical symmetries. When potential or field contours are called they should also possess the same relevant symmetries. But after zooming the planes of symmetry will have arbitrary positions on the screen. On the other hand the mesh of contour points -that is, the points used to construct the contours -will fill the screen evenly and symmetrically. The program tries to re-position the electrodes so that the contours have the expected symmetry with respect to the electrodes, but this is not always possible.
Nonzoom: this option returns to the full display limits set in the input data file (and also clears any contours etc that might have been added earlier).
Contour: this option gives 2D contour plots of potentials or electric fields or (for CPO3D and CPO3DS only) magnetic fields. In the case of potentials, a colour or a conventional contour plot can be chosen, while with electric or magnetic fields a further option of vector plots is added. Another option also exists for potentials and fields -to put numerical values on a grid into the output data file, instead of displaying contours.
The user can define the numerical limits of the field of view, to exclude unphysical exterior regions.
To generate contours the program uses N*N equally spaced grid points and calculates the values of the potential or field components at each point. The program will ask for the value of N, the inaccuracy of the calculation (for which the 'direct' method is used) and the coordinate of the contour plane in the non-viewing direction. After calculating the values at the grid points the program will ask for the number of contours and their lower and upper limits.
The option extra accuracy near electrodes controls the improvement of the calculation of potentials near to electrodes, as described in the note on potentials, fields and contours near to boundaries.
For further information see contour details.
In all the types of plot the Mouse can be used to scan the potential or field components. Two sets of information are displayed on the bottom bar -the values of the potential or field components at the nearest grid point (which appears as a small box on the plot) and the interpolated values at the position of the cursor. (The interpolated values are obtained by bilinear interpolation using the nearest 4 grid points). The units for the electric field are V/mm.
If any difficulty is encountered in clearing the contour screen, use Nonzoom.
Loss of contour symmetry when zooming: see under Zoom above.
Loss of part of picture or contours:
Parts of the picture or the contours are occasionally lost after zooming (for reasons outside our control), but can be restored by using Unzoom or Windows.
(proceed to the second part of section 5.3)