© Antony Searle / ANU 1998-1999








BLINE is a package for real-time, interactive visualisation of the magnetic field lines resulting from a wide range of magnetic geometries.
Demonstration
Power Point File
Power Point File CCP conference
Power Point Poster

BLINE was developed (using algorithms from the Pascal code of the same name by Boyd Blackwell) by Antony Searle and Ben McMillan  for and at the Plasma Research Laboratory (PRL), part of the Research School of Physical Sciences and Engineering (RSPhySSE) at the Australian National University (ANU). See http://rsphysse.anu.edu.au/prl/.  Algorithms are described in [1].  The current version is called cBline, as it has a console attached for more flexible text output, and implements pertubation calculations and coil optimization by simulated annealing.

This documentation is broken into two segments; user documentation and code documentation.  The user documentation decribes how to use the BLINE package. The code documentation will be helpful for those seeking to modify BLINE, or gain greater insight into the algorithms used.

BLINE currently operates on Microsoft Windows platforms (95/98/NT) and Linux(cBline: tested on single PIII, no stereo). There will be a substtantial performance improvement on two processor systems over single processor systems. BLINE utilises the OpenGL graphics API and will substantially benefit from a machine with an OpenGL compatible 3D accelerator card. BLINE also supports stereo viewing on machines with the necessary hardware.

For monoprocessor systems, the program's two threads will compete for system resources. The < and > keys can be used to divert more resources to the graphics/interface thread or to the solver thread that performs the calculations.
 
 

User Documentation

Using BLINE

The BLINE Input Format

Advanced features

Troubleshooting
 
 

Using BLINE

Starting BLINE

Double click on the BLINE icon, or drag the intended input file onto the BLINE icon. The program will appear as a centred 640x480 window.








The elements visible in the window are

The MENU

The on-screen pop-up menu is the main data entry point. Using the menu you can load, save, manipulate scene elements, control which scene elements are visible and at what quality, and manage the field line tracing process. To open the menu, move the mouse over it, then move the mouse over the desired options as they appear. Use the left mouse button to activate commands. For text entry boxes, appearing like the load file command [System.txt] type to change the contents of the box and then left-click or press enter to activate the command.
The Statistics Sidebar
The statistics sidebar sits on the left hand side of the screen. It displays a variety of statistics. What statistics shown, if any, can be selected from the Statistics section of the menu.
The Plane
The plane serves two important purposes. The camera will in general focus on the centre of the plane. The centre of the plane may be slid along the plane surface using the right mouse button, thus changing the focus of the camera. The orientation of the plane may also be changed using the keyboard.
 
x makes the plane perpendicular to the x axis
y makes the plane perpendicular to the y axis
z makes the plane perpendicular to the z axis
b makes the plane perpendicular to the magnetic field at the centre of the plane
n makes the plane perependicular to the line of sight
The second purpose of the plane is to act as a Poincare Section. The plane records and shows the points at which magnetic field lines cross it.

You can make the Plane invisible using the Menu|View|Poincare Section|Visible command.

Loading a file
BLINE supports three ways to load files - as a command line argument, a menu command and as a drag-and-drop recipient. Thus to load an input file such as System.txt you may use one of the following
Type BLINE System.txt at the command line

Drag System.txt onto the BLINE executable's icon Bline.exe (this will start a new BLINE instance even if there is one already running)

Use the Menu|File|Load|System command. To do this, expand out the menu as above, then with the mouse over the text entry field which defaults to [System.txt] left-click or press enter. To load a different file, use backspace and type a different name. Note that all keyboard commands are suspended while a text entry field is active.

Drag the System.txt icon onto the BLINE window.

The loaded file will be displayed in the window.








Each file is made up of a combination of two sorts of objects, Polygones (orange) and Meshes (white), grouped together into SystemElements. Polygones are made up of current-carrying wires. These generate a magnetic field. Meshes typically enclose regions of interest. They contain the magnetic field sampled at the vertices of a 3D grid. For complex geometries it is substantially faster to evaluate an approximate magnetic field for a point by interpolating between surrounding mesh points than it is to analytically calculate the magnetic field fom the Polygone wires.

If the file has been used begfore and saved, there will be a binary cache file, with the same file name but a .bin extension. This will be loaded in preference to the text version as

It is faster to load the preparsed data

The .bin file stores the magntic field values in the mesh, eliminating the need to compute them every time a file is loaded.

BLINE intelligently detects if the source file as been altered since a cache file was produced, and if the cache is out of date BLINE disregards it.

You may load files on top of each other, adding their Polygones and Meshes to the model. To close all the files, use the Menu|File|Close command. To remove only a certain element from the model, use the Menu|Elements|Select Next command until the element turns green, then use the Menu|Elements|Delete command to remove it.

Viewing the model
To view the model, use the arrow keys or numpad to rotate the model. The numpad plus (+) and minus (-) keys zoom the camera in and out. The 7 and 9 keys on the numpad roll the camera. If you become disoriented, hit 5 on the numpad to return to the initial position. (check that numlock is on if these commands do not seem to work).

Pressing P will move the camera perpendicular to the plane, allowing easier viewing of punctures (see below).

Tracing Magnetic Field (B) Lines
When the program starts it defaults to calculating the magnetic field vectors at mesh vertices. To toggle between this background mode and tracing field lines press T or use the Menu|Trace|Active switch.

Field lines are represented as blue lines. The line should get longer as the program traces.

If the field line is outside any meshes, it will analytically calculate the magnetic field from the Polygones.

If the field line is inside a mesh, it's behaviour will be governed by the Menu|Trace|Interpolation setting, which controls the trace quality.
 
1 Lowest quality

The magnetic field is taken from the nearest grid vertex.

2 Medium quality

The magnetic field is a (tri)linear interpolation within the mesh cell surrounding the field line

3 High quality

The magnetic field is a (tri)spline interpolation within the mesh cell surrounding the field line. The default setting.

4 Highest quality

The magnetic field is exactly calculated from the Polygone fields without using the mesh.

If the field line attempts to use the magnetic field produced by a mesh, BLINE checks to ensure that the vertices used have been defined. If they are not defined, BLINE calculates them analytically before returning the value. This means that if meshes are initially unfilled, the mesh interpolation methods can be slower than analytic methods, until the regions of the mesh are filled.
When the program uses a mesh method to determine the magnetic field, the cell being used is displayed as eight white dots. This shows
Which mesh(es) are active

Where the active end of the field line is

What the mesh cell size(s) is(/are)

When a complex geometry is loaded, it is sensible to switch to an analytic method initially, then spend time filling the meshes, either by switching off the trace, which will prompt background filling of the meshes, or by changing to a non-analytic method, which will fill the mesh wherever the field line wanders.








A field line may be restarted anywhere on the Plane by left-clicking. Wherever the field line intersects the plane, it will leave a point. If you start a new trace, the points of the old trace(s) will be visible as a darker green until the plane is cleared (either by pressing C or by changing the plane orientation.)

The display of the field line may be controlled with the Menu|View|Field Line commands.

Use Visible to toggle display of the field line.

Use Elements to control how many lines are drawn. This value may be decreased to improve the frame rate.

Use Resolution to improve the resolution of the lines if sharp corners become apparent.

The commands under Menu|View|Poincare Section have similar roles. Here the Resolution may be incresed to see more of the history of the Poincare points at the expense of not displaying pointis throughot this range.

All the trace is stored in an expanding buffer in memory, not merely the displayed portion. Because of this, when tracing it is wise to keep an eye on the Memory statistic, and stop tracing if this approaches your system's memory limit. Never leave a trace running unattended, as it will potentially fill system memory, degrading the rest of your system and possibly resulting in data loss.

The step length of the trace may be altered withMenu|Trace|Step Size.

The mesh may become inaccurate near to coils as the feld changes so rapidly that the interpolation is insufficent. The Menu|Trace|Proximity setting cotrols how close a field line may get to a Polygone segment before resorting to an analytic solution.
 
 

Saving a file
To save any changes you have made to the geometry of a scene or to save filled or partially filled meshes so that you will not have to wait while they are generated in future, use the Menu|File|Save|System command to enter a filename and save. To save a specific portion of the geometry, use Menu|Elements|Select Next to select it then Menu|Elements|Save.

Note that even if the input file is unchanged, it will be overwritten, and any comments will be lost. Thus it is wise to save to a different filename to any that may need to be edited by hand in the future. For instance, you may manually compose System.txt. If you save to System.txt all your comments will be lost. Thus you should save to System2.txt. In future, load System2.txt. If you wish to edit the scene by hand, edit System.txt and then load it, and save it to System2.txt.

The BLINE Input Format
BLINE reads in standard text files describing the scene. When reading the files, BLINE ignores all characters except numbers, so comments may be included anywhere, but MUST NOT include numeric characters. Thus, any format may be adopted which does not interfere with the order in which these numbers are placed.
(V3 Note: free form input partially implemented, relatively unrestricted comments are allowed in the first part of the header, see input/h1v3.txt for an example)

Despite this, there is a preferred format. This is the format to which BLINE saves text files.

 
BLINE System file

SystemElements = 2
SystemElement {
Transform {
1 0 0
0 1 0
0 0 1
0 0 0
}
Polygones = 2
Polygone {
Elements = 4
Current = 1
< -1 -1 0 >
< -1 -3 0 >
< 1 -3 0 >
< 1 -1 0 >
< -1 -1 0 >
}
Polygone {
Elements = 4
Current = 1
< -1 1 0 >
< -1 3 0 >
< 1 3 0 >
< 1 1 0 >
< -1 1 0 >
}
Meshes = 1
Mesh {
Transform {
0.125 0 0
0 0.125 0
0 0 0.125
-4 -4 -4
}
64 64 64
}
}
SystemElement {
Transform {
1 0 0
0 0 1
0 -1 0
0 0 0
}
Polygones = 2
Polygone {
Elements = 4
Current = 1
< -1 -1 0 >
< -1 -3 0 >
< 1 -3 0 >
< 1 -1 0 >
< -1 -1 0 >
}
Polygone {
Elements = 4
Current = 1
< -1 1 0 >
< -1 3 0 >
< 1 3 0 >
< 1 1 0 >
< -1 1 0 >
}
Meshes = 1
Mesh {
Transform {
0.125 0 0
0 0.125 0
0 0 0.125
-4 -4 -4
}
64 64 64
}
}

The first number included is the SystemElement count. This tells BLINE how many SystemElement objects are present in the file.
 

SystemElements = 2

Each SystemElement is constructed of an arbitrary number of two types of objects, Polygones and Meshes.

The first item expected in a SystemElement is a Transform. This is an array of 12 numbers, corresponding to a matrix transformation. Matrix transformations are used in BLINE to allow the ready rotation and translation of objects without interfering with the actual data.

Breaking the 12 numbers into four triplets, each triplet is a three-vector. The first is the vector to which a unit step along the x axis will be mapped, the second a unit step along the y axis and the third a unit step along the z axis. The final triplet is the position of th new origin, or where (0, 0, 0) will be mapped to.

Thus, the identity transform, which does nothing, is

< 1 0 0 > < 0 1 0 > < 0 0 1 > < 0 0 0 >
A translation to a new origin at (1, 2, 3) is 
< 1 0 0 > < 0 1 0 > < 0 0 1 > < 1 2 3 >
And a 90 degree rotation around the z axis is given by
< 0 1 0 > < -1 0 0 > < 0 0 1 > < 0 0 0 >
The next number is the Polygone count. This tells BLINE how many Polygones are present in the SystemElement. This number may be zero, but there is no point having a SystemElement that does not generate any magnetic field.
Polygones = 2
The Polygone count is followed by an appropriate number of Polygone objects. Each Polygone consists of an Element count, a current strength and then Elements + 1 vectors defining the vertices of the wires. In general, Polygones will be closed (the first and last elements the same) but they may be open, for instance to permit the splitting of one wire into two carrying lesser currents.
Polygone {
Elements = 1

Current = 1

< 0, 0, 0 >

< 1, 1, 1 >

}

The current defined runs through a wire running in straight segments between the points given. The element count refers to the number of straight segments, not the number of vertices.

After the appropriate number of Polygones have been defined, mesh definition begins.

Firstly a number indicating the number of meshes present is given

Meshes = 1
Then each mesh (if any) is defined, by a transform followed by a triplet of numbers. This triplet defines the size of the mesh in the x, y, z directions. They will be rounded up to the nearest power of two, so it is sensible to enter them as some power of two (2, 4, 8, 16, 32, 64, 128...). Meshes can easily consume huge amounts of memory, using roughly 32 bytes for every element. Thus a cubic mesh with 128 elements to each side will consume 64 megabytes of memory.

To position the mesh, use the offset (last triplet) of the transform to manipulate corner, and use the remaining triplets to sacle the cell appropriately. For instance, to make a 64x64x64 mesh into an 8x8x8 cube centred at the origin, the axes must be scaled by 8/64 = 0.125 and the corner must be moved to (-4, -4, 4).

The Meshes complete the Polygone object.

Files
See bline_notes_2007_8.txt for a "train-of-consciousness" commentary on versions, input directory and list of files.

Advanced Features

BLINE contains several features for advanced users, and a number of experimental features which may not work correctly under all conditions.
Using the commands in Menu|Elements, the selected element can be translated along or rotated about the x, y or z axes. The current running through the polygones in the element can also be scaled by any factor.

Pressing F will take BLINE to fullscreen mode. Note that this option may cause visual artefacts if there is sparse geometry and a high frame rate. Press F again to return to normal mode.

Pressing S will take BLINE to stereo mode. This option will lower the frame rate, and on systems without stereo support have no other effect. On systems with stereo suppport, BLINE will be displayed in full stereo, giving enhanced depth perception. Press S to return to normal mode.

Stereo and fullscreen mode are independent and compatible.

Pressing V will take BLINE to an orthographic (isometric) view. Note that this option should not be used with stereo viewing (a stereo orthographic view will produce incorrect visual depth-cueing, which might be helpful in some circumstances). This mode is useful for measurement and alignment checks. Press V again to return to normal mode.

Pressing A will toggle Antialiasing on and off. Antialiasing is off by default, and when turned on may improve image quality.

Pressing D will toggle the depth (z) buffer on and off. The depth buffer keeps objects drawn in the right order, but slows down drawing. It has negligable effect on wireframe drawing and may be turned off under such conditions.

F2-F12 can be used to store and return to camera positions. Press shift+function key to save a camera position, press the function key to restore it. F1 will return the user to the last camera position.

Pressing R will toggle a rollercoaster ride along the current field line!

"Screenshot" images can be taken by pressing I. The screenshot is saved in the executable directory, to "Screen.bmp".

On single processor systems, the < and > keys can be used to control the responsiveness of the system, by altering thread behaviour.

Experimental features and known bugs
Flux Surface
When Q is pressed, BLINE attempts to construct a flux surface from the current trace. This will only function correctly under certain conditions.
The trace must be sufficently long

The trace must present a well-defined surface. To see this, check a Poincare section of the trace. If there is significant noise, or sparse points, or the trace does not form a well-defined tube, then the flux surface may fail.

If the trace is a magnetic island, the flux surface will be composed of too many triangles for convenient display.

The flux surface may be "inside out", that is it appears as a triangle mesh rather than as a solid surface. If this is the case, press O to reorient the surface.

Creating a flux surface may cause BLINE to crash.

Trace termination
If a trace is left running it will request memory until system memory is exhausted. NEVER leave a trace running unattended.
Troubleshooting
First, check the documentation above to see if the problem is a known bug or simply proper program behaviour.
Problems | Solutions
The display is corrupted
Make sure that you have a colour depth of 16 bits per pixel (65536/64k colours) or better.
BLINE graphics are too slow, input is sluggish or BLINE solving is too slow
On single processor machines this may mean that resources are being poorly allocated. Use the < and > keys to divert more or less resources to or from the graphical and/or solver components.
The frame rate is very slow, even when almost nothing is being drawn
Software drawing may be occuring. If you have an OpenGL compatible accelerator card, the window may be be too big or the screen size too large for acclereation to occur. If you do not have an openGL accelerator card, decrease the size of the window, or upgrade to a faster processor and accelerator!
Stereo doesn't work, even though my card supports stereo.
The window may be too big, or the screen size too large.
Tracing is very slow.
Change to a lower quality. If this doesn't help much, turn off tracing. If blue lines are scanning across the meshes, they are not yet full. Wait a while until the scanning stops. The meshes are now full and should speed up tracing.
Code Documentation

BLINE is a multithreaded program. On initialisation, the initial thread (the Draw Thread) progresses into a message loop as normal, and a second thread (the Solver Thread) is started. The Draw Thread handles windows messages, refreshes the screen and handles user input, either directly or by setting flags which the solver thread processes when convenient. Thus the primary job of the draw thread is reading from the program data to display it to the screen. The primary job of the solver thread is to perform the calculations necessary to produce data and to write it. This means that the manner in which data is written by the solver thread must occur in such a fashion that the data is always valid.

Program data is stored by a class heierarchy. A single instance of the System class, called MagneticSystem is the root. Following a general design priciple, the System class primarily consists of a pointer Element and an integer Elements. The pointer is dynamically allocated memory, with Elements storing the number of elements contained in the memory. For the System class, it is objects of the SystemElement class. Each SystemElement conatins pointers and counts to Mesh and Polygone objects, and contains a transformation to the space of the polygones. The Polygones are simply vertex lists that correspond to linked straight wire segments, and the Meshes are huge arrays of MeshElement data, holding field information and the distance to the nearest Polygone.

To trace a field line, the program extracts a magnetic field at a ceratin position from the MagneticSystem. This request is passed to the SystemElements and their return summed. A the SystemElement level, depending on the trace quality the field is extracted by interpolation from the mesh or analytically from the polygones. If the mesh is used and refers to an undefined MeshElement (marked by a negative distance) then that MeshElement is automatically filled before returning, using the backpointer parent in the mesh structure. Appropriate transformations occur throughout.

The field data thus obtained is fed into an Adams-Bashforth Adams-Moulton predictor-corrector algorithm, which has the advantage of requiring only one evaluation per step (as it is the field evaluation which is by far the most time consuming part of the code)

The object-oriented nature of the code means that functions are modular and have similar or identical behaviour over a wide range of classes.

Note that operator overloading has been used to implement vectors for convenience.

The code is well commented, and this should be sufficent to explain the details.

Tasks

Rigorously check the spline interpolation routine, as it appears less accurate than it should be. [done, fixed BB 2007]

Implement a structural input file format (true XML?) so that parse errors can be detected.

Implement additional field generating elements - such as circles. [implemented in a fudgey way - polygones with -1 elements]

Optomise analytic field evaluation in Polygone::Field (extern asm?)

Implement third order puncture interpolation

Wedge version produced December 1999 by A.C. Searle.

Keys added in Second Version

E toggle area determination v1.9/reset plane origin v2.0
J start analysis/proceed to next stage
G Restart trace at position given in menu
U Toggle Runge-Kutta / Linear Start
W Stop Inertial Drift at this point, and Clear the scroll list
C Clear punctures

Command Line Arguments

-m small memory use (as of v2.01: Starts with about 17MB, peaks at 105MB, compared to starting with 35MB, peaking at 150MB)
-p enable processing, such as transform optimisation - later will accept a numeric argument to specify type of processing
-a -f -s (antialias, full screen, stereo) as for interactive  controls
-q quick setup - not yet implemented

[1] Algorithms for Real Time Magnetic Field Tracing and Optimisation, B.D. Blackwell,  Ben.F.McMillan, A.C. Searle and H.J. Gardner, for Computer Physics Communications.

 
Antony Searle 1999 ANU PRL