Illuminator Distributed Visualization Library

Adam Powell

Version 0.8.9 released August 17, 2004
Built August 18, 2004 for a pc i686 running linux-gnu

Abstract: Illuminator is a library whose current primary purpose is to graph PETSc 3-D distributed arrays' isoquant contour surfaces using Geomview. It is not at all ``complete'', rather a first cut. It currently creates the contour surface triangulation in parallel, then sends all of the triangles to the first node for display. Future plans include making the display process more efficient on that first node, and later doing some kind of distributed rendering for faster visualization without the use of Geomview. As of version 0.4, Illuminator also does distributed storage and retrieval of distributed arrays of any dimensionality, allowing local hard drives on Beowulf cluster nodes to act as a single giant ``RAID-0'' array with extremely high bandwidth; this can be used for fast retrieval and visualization of time series data.

Table of Contents

Chapter 1  Introduction

PETSc is a great distributed object manager and Newton-Krylov nonlinear system solver. Geomview is a wonderful 3-D surface visualization tool. It seemed logical marry the two, and produce isoquant contour surfaces from PETSc distributed objects in parallel, then display them using Geomview.

This is a first cut attempt at such a project. Each node generates its own isoquant contour surface(s), then all of those generated triangles are gathered to the first node for viewing in Geomview. Right now, it does not do a very efficient job of this: it sends three vertices for each triangle to the first node, which sends those three vertices to Geomview, in plain text format. In the future, it may do a number of things to reduce the number of triangles involved, reduce the number of vertices generated per triangle, and more efficiently transmit the vertices to Geomview.

Long-term, there are other nice 3-D viewers out there such as Data Explorer from IBM, some kind of unified front end to them would be nice. Furthermore, with parallel array storage, much more powerful parallel visualization concepts are possible. Like if we can assign to each point a certain luminosity and transparency, it's easy to integrate those values along a line through the locally-stored part of the array to produce a total transparency and luminosity for that line in the local array, then just combine that with other line integrals through the other local sections (maybe in e-vas?), and we have generated a total image in parallel. However, to do this easily each section must be convex, or there will likely be regions with points both in front and behind a given other region; so this will work with PETSc distributed arrays, but not with general partitioned finite element meshes. But as you can see, this opens many interesting avenues for exploration...

For now, this humble beginning. Share and enjoy.

Chapter 2  Frequently Asked Questions

2.1  General install problems

Q: ``make dist'' doesn't work. What's up with that?

A: That's because automake 1.4 doesn't like foreign variables from included makefiles, like PETSC_DM_LIB used here. For this reason, illuminator through 0.3.0 had targets mydistdir, mydist and mydistcheck in Makefile.am, use those instead of distdir, dist and distcheck. For 0.3.1 and beyond, you must use automake 1.5 or higher.

Chapter 3  Developer's Manual

Illuminator is intended for developers who are familiar with PETSc and want to visualize distributed arrays, and as such, this manual assumes knowledge of PETSc programming.

For more details, refer to the complete source code reference which begins at appendix C.

3.1  Visualization

With a bit of PETSc programming knowledge, using Illuminator is pretty simple. Start by invoking GeomviewBegin() (appendix I.2.1) to open the Geomview display and the pipes to and from Geomview.

At an appropriate checkpoint in the program, invoke DATriangulate(), or for a local array DATriangulateLocal(), or else their DATriangulate(Local)Range() variants (appendices H.2.2 and H.2.1), to create the distributed triangulation on each processor. When that is complete, the function GeomviewDisplayTriangulation() (appendix I.2.2) gathers the triangulations to node 0, sends them to Geomview and resets the triangle counts to zero. This cycle of DATriangulate() and GeomviewDisplayTriangulation() may be repeated as necessary, subsequent cycles simply replace the existing triangle set in Geomview with a new set of triangles. In the example program chts, this is done in the function ch_ts_monitor() (appendix M.2.5) whose function pointer is passed to PETSc's TS_Set_Monitor() so it displays the contour surfaces at the end of every timestep calculation.

Finally, when you are done, call GeomviewEnd() (appendix I.2.3) to exit the Geomview process and close its pipes.

3.1.1  Significant bug

If an isoquant surface happens to exactly intersect one or more of the vertices, the triangles on the adjacent tetrahedra may be generated with coordinates ``nan nan nan''. This is a problem, and I'll try to figure out a solution at some point. In the meantime, the workaround is to choose a slightly different isoquant surface value to avoid the intersection (e.g. if 1000 intersects a vertex, then try 999.999).

3.2  Distributed storage

Because 3-D timestep data can be quite voluminous, Illuminator comes with functions for distributed loading and storage of data. That is, if you have a Beowulf cluster with a hard disk on each node, why send all of the data to the head node to store it? That would be a waste of bandwidth, and would neglect the available local hard drive storage!

Instead, you can use Illuminator's function IlluMultiSave() (appendix G.1.3) to save the local data to a local hard drive. This will create two files for each CPU, {basename}.cpu####.meta which contains XML-formatted metadata describing that CPU's data, and {basename}.cpu####.data, which contains the data stored in the distributed array (#### is the CPU number). The data can be compressed using gzip and/or by converting floating point values to 32-, 16- or 8-bit integers scaled to the minimum and maximum values of each field. The function IlluMultiLoad() (appendix G.1.1) creates a new distributed array based on the stored data, and IlluMultiRead() (appendix G.1.2) reads the stored data into an existing distributed array and vector, after verifying a match between existing and stored distributed array parameters.

It is also possible to save a distributed array stored on multiple CPUs, and load/read it back into a single CPU, IlluMultiLoad() and IlluMultiRead() automatically rearrange the data at load time accordingly. At some point, it may be possible to load to arbitrary numbers of CPUs, but for now, only n® n and n® 1 storage/loading are supported.

IlluMultiSave() saves in the native byte order of the CPU on which it is compiled, and IlluMultiLoad() and IlluMultiRead() will automatically byte-swap if stored data doesn't match the CPU's endianness.

Chapter 4  Example: Transient Cahn-Hilliard chts.c

The example program provided with Illuminator solves the Cahn-Hilliard equation in 3-D. The implementation is split into files cahnhill.c (appendix N) containing all of the free energy functions, derivatives, etc.; and chts.c (appendix M) with main(), initialization, callbacks---essentially, the overhead of the program; and a small header with the data structure in cahnhill.h (appendix O). The calls to Illuminator library functions are contained in chts.c.

The idea behind Cahn-Hilliard is that we have a concentration field C, with associated thermodynamic free energy density f given by
  f =
a
2
| Ñ C | 2 + bY(C),     (4.1)
where the two terms are the gradient penalty and homogeneous free energy Y, and a and b are model constants. This functional form was first used to explain the finite domain size during the initial phase separation in spinodal decomposition. A simple polynomial homogeneous free energy function (the one used in cahnhill.c) looks like
  Y = C2 (1-C)2.     (4.2)
This functional form gives two stable equilibria (minima) at C=0 and C=1, and an unstable equilibrium (maximum) at C=1/2.

The total free energy of the system occupying the body W is
  F = ó
õ
 


W
f dV.     (4.3)
The ``chemical'' potential µ is given by
  µ =
d F
d C
= -a Ñ2 C + bY'(C),     (4.4)
which leads to the transport equation
 
C
t
= Ñ· ( kѵ )     (4.5)
where k is the mobility.

The interface thickness e is on the order of a/b, and the surface energy g on the order of ab, so we can set a=ge and b=g/e, with constants which we'll worry about later.

Returning to equation 4.5, it expands to
 
C
t
= Ñk·Ñµ + kÑ2µ     (4.6)
and further in terms of C to
 
C
t
= Ñk·Ñ(-aÑ2C + bY') - kÑ2(aÑ2C+bÑ2Y'(C))     (4.7)

Now we turn to the PETSc implementation, using distributed arrays and TS timestepping solvers. The nonlinear timestepping code uses runtime-selectable timestepping solvers (explicit, implicit, or default Crank-Nicholson) to solve the equation
 
ui
t
= Fi(uj),     (4.8)
where ui is the vector of unknowns (here concentrations). This is converted by PETSc into a system of nonlinear equations according to the solver type and then solved using its SNES solvers, but we must provide subroutines to calculate Fi and the derivatives Fi/ uj which are used to calculate the Jacobian of the nonlinear system (unless running matrix-free using the -snes_mf option). Starting for now with constant k, a and b, the Fi are given by
  Fi = k ( -aÑ2Ñ2C + bÑ2Y'(C) )     (4.9)
Let's suppose C is on a 2-D finite difference mesh with uniform but possibly different spacings hx and hy in the x- and y-directions, so we'll let Cx,y be the value of C at coordinates (xhx, yhy) for integer x and y.

Starting with the b term, the Laplacian Ñ2Y'(C) at (x,y) can be approximated using the standard 5-node finite difference stencil:
  Ñ2Y'(C) ~
Y'(Cx-1,y)-2Y'(Cx,y)+Y'(Cx+1,y)
hx2
+
Y'(Cx,y-1)-2Y'(Cx,y)+Y'(Cx,y+1)
hy2
    (4.10)
or expressed slightly differently, as the sum of the terms:
 
  Y'(Cx,y+1)hy-2  
Y'(Cx-1,y)hx-2 Y'(Cx,y)(-2hx-2 -2hy-2) Y'(Cx+1,y)hx-2
  Y'(Cx,y-1)hy-2
    (4.11)
So the product of kb and this is one part of the function Fi, and that part of the derivative Fi/ Cj for the Jacobian is simply the appropriate coefficient from equation 4.11 times the second derivative Y''(C) evaluated at the appropriate point.

For the a-term, the Laplacian of the Laplacian (also known as the biharmonic operator) is a bit more messy. Using the notation in equation 4.11 but only in the first quadrant (the coefficients are symmetric), the term will be -ka times:
 
    Cx,y+2hy-4    
  ... Cx,y+1(-4hy-4-4hx-2hy-2) 2Cx+1,y+1hx-2hy-2  
... ... Cx,y(6hx-4+6hy-4+8hx-2hy-2) Cx+1,y(-4hx-4-4hx-2hy-2) Cx+2,yhx-4
  ... ... ...  
    ...  
    (4.12)
(ellipsis indicates symmetry). This is quite a bit more complicated, but at least it's linear so the derivatives Fi/ Cj are constant.

These Fi functions are calculated by the function ch_residual_2d() (appendix N.1.9) and assembled into a PETSc vector in ch_residual_vector_2d() (appendix N.1.5). The derivatives are calculated in two parts: the a term's derivative matrix is built at the start of the run in ch_jacobian_alpha_2d() (appendix N.1.3), and with each nonlinear iteration, the b term's derivative matrix is added to that in ch_jacobian_2d() (appendix N.1.1).

Note that this is all in 2-D; the 3-D version is left as an exercise to the reader, though it's already coded in the corresponding _3d functions in cahnhill.c.

Chapter 5  Appendix

@.1  Version History

A brief summary of information in the ChangeLog file.

@.1.1  PETScGraphics 0.1

The first release, this included basic functionality of making and displaying multiple transparent contour surfaces in 3-D, but only in uniprocessor operation.

@.1.2  PETScGraphics 0.2

This release included the first truly parallel visualization, including gathering of the triangles to node 1 for viewing. It also included lots of code cleanup, changes from the PETSc coding style to something more like GNU format. And it added the -random flag to the chts test program for random initialization.

@.1.3  PETScGraphics 0.2.1

This was largely a documentation update to the new 0.2 interface, reflecting changes to the new version.

@.1.4  PETScGraphics 0.2.2

More documentation updates, esp. for the example program; minor changes to support gcc on Alpha processors; chts -twodee now works.

@.1.5  Illuminator 0.2.3

Name change, as PETSc may be one of several backends in the future. Shuffled some functions around to petsc.c and geomview.c.

@.1.6  Illuminator 0.2.4

Updated to work with PETSc 2.1.1.

@.1.7  Illuminator 0.2.5

Minor fixes: loops in DATriangulate now work for non-periodic distributed arrays; changed VecMin() and VecMax() to VecStrideMin() and VecStrideMax() to properly obtain the minimum and maximum value of the target field.

@.1.8  Illuminator 0.3.0

A major new addition is the chui (Cahn-Hilliard User Interface) program, this is not quite complete but illustrates what can be done with a bit of libglade. The goal is eventually to use this kind of thing and Illuminator to provide an interactive distributed simulation.

@.1.9  Illuminator 0.3.1

A bugfix release, among other things this gets chui.glade into the distribution (which sort of helps), and requires automake 1.5 or above.

@.1.10  Illuminator 0.3.2

Another bugfix release, changed Makefile.am to remove static libs/objects from shared libluminate to fix building on PIC-sensitive platforms.

@.1.11  Illuminator 0.4.0

Major addition: the IlluMulti system for extreme performance distributed storage of PETSc distributed arrays on local disks of Beowulf cluster nodes. This is intended to enable rapid (real-time?) distributed creation of visualization movies from distributed timestep data stored on the local drives, essentially turning those hard drives into a giant RAID-0 array. For details, see the source-embedded documentation in appendix G.

@.1.12  Illuminator 0.4.1

Primarily a bugfix release (since 0.4.0 didn't compile out of the box), this version also adds the 3dgf program, designed to make it very easy to visualize the isoquant surfaces of a function in 3-D. As the name implies, it has a couple of simple Green's functions in it now, and the distributed nature of the function computation lends it to efficient parallel computation and visualization of more complex Green's functions. At some point this should have a chui-like libglade-based interface to make interactive modification of isoquants, colors, limits, resolution, function parameters and such a lot easier.

@.1.13  Illuminator 0.4.2

One bugfix: illuminator.m4 now installs. Added debian directory to make future upgrades package more easily.

@.1.14  Illuminator 0.4.3

Subtle bugfixes for IlluMultiLoad() and IlluMultiRead(), needed for large n® 1 redistributions, and one bugfix for GeomviewDisplayTriangulation().

@.1.15  Illuminator 0.4.4

Subtle bugfix for IlluMultiParseXML(); added tsview program for generic viewing of timestep data (just 2-D for now; moved from RheoPlast). Also added a --with-geomview= configuration option.

@.1.16  Illuminator 0.5.0

New DATriangulateLocal() function should save time when the local array is available; transparency option in GeomviewDisplayTriangulation(); tsview supports 3-D, with ability to cycle through displayed field and turn transparency on and off at will.

@.1.17  Illuminator 0.6.0

Two new attributes added to IlluMulti file format, now version 0.2: field visualization types to tag special scalar, vector, and even tensor fields; and floating-point size of the ``physical'' array in each direction. Support added to tsview for physical size in 2-D (was already there in 3-D).

@.1.18  Illuminator 0.6.1

New field visualization types, small change to 0.2 IlluMulti file format, little bug fixes. (This is a ``brown paper bag'' release.)

@.1.19  Illuminator 0.6.2

Bug fixes for tsview viewer: non-square/cube geometry, ``v'' command to change fields in 3-D, and field name for 3-D all now work properly.

@.1.20  Illuminator 0.6.9

New tsview commands: ``s'' (size PetscViewer windows in 2-D) and ``p'' (set plot contours in 3-D). Also new HeVeA LATEX to HTML translator option, with updates to much of the documentation build system. And a preview of the new tsview called tsview-ng, which is sufficiently premature that it is not included in the Debian package, but will be a substantial new addition to 0.7.0 (hence 0.6.9 for this version).

@.1.21  Illuminator 0.7.0

A private release, with new DATriangulateLocal function, new cut options for DATriangulate(Local), three new tsview commands, readline support in tsview, and a new -vector_max option to tsview-ng to scale the maximum vector size.

@.1.22  Illuminator 0.8.0

Upgrade chui and tsview-ng to gtk+/GNOME version 2 libraries, including new .desktop entries. The recommended 2-D viewer is now tsview-ng.

@.1.23  Illuminator 0.8.9

Fix for tsview-ng so it can really be recommended. Moved 2-D rendering from tsview-ng into the library, and added a prototype for 3-D (planned to work in 0.9). New variations on DATriangulate(Local) create triangles for just a range of grid points.

@.2  Copying

Illuminator Distributed Visualization Library

Copyright (C) 2001, 2002 Adam Powell; Copyright (C) 2003, 2004 Adam Powell, Bo Zhou, Jorge Vieyra and Wanida Pongsaksawad

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

Note that it uses some chunks of code from Ken Brakke's public domain Surface Evolver, those chunks are attributed in the source code.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

You may contact the author by email at hazelsct@mit.edu.

@.3  File illuminator.h

RCS Header: /cvsroot/petscgraphics/illuminator.h,v 1.22 2004/08/17 15:05:42 hazelsct Exp




This is the interface for the Illuminator library.

Included Files

#include </usr/lib/petsc/include/petscda.h>



#include </usr/include/glib-2.0/glib.h>


Preprocessor definitions

#define ILLUMINATOR_H


#define COMPRESS_INT_MASK 0x30


#define COMPRESS_INT_NONE 0x00


#define COMPRESS_INT_LONG 0x10


#define COMPRESS_INT_SHORT 0x20


#define COMPRESS_INT_CHAR 0x30


#define COMPRESS_GZIP_MASK 0x0F


#define COMPRESS_GZIP_NONE 0x00


#define COMPRESS_GZIP_FAST 0x01


#define COMPRESS_GZIP_BEST 0x0A

@.3.1  Type definitions

Typedef field_plot_type

A value of field_plot_type is attached to each field in a simulation in order to visualize them properly. Types are as follows:


typedef enum {...} field_plot_type


enum
 {
 FIELD_SCALAR;Scalar field.
 FIELD_TERNARY;Ternary composition field with two components (third component is inferred from first two).
 FIELD_VECTOR;Vector field.
cxreftabiia  FIELD_TENSOR_FULL;Full ds*ds tensor field, e.g. transformation.
 FIELD_TENSOR_SYMMETRIC;Symmetric tensor field (using lines in principal stress directions).
 FIELD_TENSOR_SYMMETRIC_ZERODIAG;Symmetric tensor field, inferring last diagonal from the opposite of the sum of the others.
 }


@.3.2  Functions

Local Function DATriangulate()

static inline int DATriangulate ( DA theda, Vec globalX, int this, PetscScalar* minmax, int n_quants, PetscScalar* isoquants, PetscScalar* colors, PetscTruth xcut, PetscTruth ycut, PetscTruth zcut )

Local Function DATriangulateLocal()

static inline int DATriangulateLocal ( DA theda, Vec localX, int this, PetscScalar* minmax, int n_quants, PetscScalar* isoquants, PetscScalar* colors, PetscTruth xcut, PetscTruth ycut, PetscTruth zcut )

@.4  File illuminator.c

RCS Header: /cvsroot/petscgraphics/illuminator.c,v 1.9 2004/08/17 15:05:56 hazelsct Exp




This is the illuminator.c main file. It has all of the routines which compute the triangulation in a distributed way.

Included Files

#include "config.h"config.h



#include "illuminator.h"illuminator.h
 #include </usr/lib/petsc/include/petscda.h>
 #include </usr/include/glib-2.0/glib.h>


Preprocessor definitions

#define MAX_TRIANGLES 2000000


#define __FUNCT__ "storetri"


#define __FUNCT__ "DrawTetWithPlane"


#define COORD( c1, c2, index )


#define __FUNCT__ "DrawTet"


#define __FUNCT__ "DrawHex"


#define __FUNCT__ "Draw3DBlock"

@.4.1  Variables

Variable num_triangles

Number of triangles in this node. Its value is initialized to zero, and incremented as each triangle is added, then reset to zero when the triangulation is displayed.


int num_triangles

Variable vertices

Array of vertex corners, whose size is fixed by MAX_TRIANGLES. For each triangle, this array has the coordinates of the three nodes, and its R, G, B and A color values, hence 13 PetscScalars for each triangle.


PetscScalar vertices[13*2000000]

@.4.2  Functions

Global Function Draw3DBlock()

Calculate vertices of isoquant triangle(s) in a 3-D array of right regular hexahedra. This loops through a 3-D array and calls DrawHex to calculate the triangulation of each hexahedral cell.


int Draw3DBlock ( int xd, int yd, int zd, int xs, int ys, int zs, int xm, int ym, int zm, PetscScalar* minmax, PetscScalar* vals, int skip, int n_quants, PetscScalar* isoquants, PetscScalar* colors )


int Draw3DBlock Returns 0 or an error code. int xd Overall x-width of function value array. int yd Overall y-width of function value array. int zd Overall z-width of function value array. int xs X-index of the start of the array section we'd like to draw. int ys Y-index of the start of the array section we'd like to draw. int zs Z-index of the start of the array section we'd like to draw. int xm X-width of the array section we'd like to draw. int ym Y-width of the array section we'd like to draw. int zm Z-width of the array section we'd like to draw. PetscScalar* minmax Position of block corners: xmin, xmax, ymin, ymax, zmin, zmax. PetscScalar* vals The array of function values at vertices. int skip Number of interlaced fields in this array. int n_quants Number of isoquant surfaces to draw (isoquant values). PetscScalar* isoquants Array of function values at which to draw triangles. PetscScalar* colors Array of color R,G,B,A quads for each isoquant.

Global Function DrawHex()

This divides a right regular hexahedron into tetrahedra, and loops over them to generate triangles on each one. It calculates edge and whichplane parameters so it can use DrawTetWithPlane directly.


int DrawHex ( PetscScalar* coords, PetscScalar* vals, PetscScalar isoquant, PetscScalar* color )


int DrawHex Returns 0 or an error code. PetscScalar* coords Coordinates of hexahedron corner points: xmin, xmax, ymin, etc. PetscScalar* vals Function values at hexahedron corners: f0, f1, f2, etc. PetscScalar isoquant Function value at which to draw triangles. PetscScalar* color R,G,B,A quad for this hexahedron.

Global Function DrawTet()

This sets the edge and whichplane parameters and then passes everything to DrawTetWithPlane to actually draw the triangle. It is intended for use by developers with distributed arrays based on tetrahedra, e.g. a finite element mesh.


int DrawTet ( PetscScalar* coords, PetscScalar* vals, PetscScalar isoquant, PetscScalar* color )


int DrawTet Returns 0 or an error code. PetscScalar* coords Coordinates of tetrahedron corner points: x0, y0, z0, x1, etc. PetscScalar* vals Function values at tetrahedron corners: f0, f1, f2, f3. PetscScalar isoquant Function value at which to draw triangle. PetscScalar* color R,G,B,A quad for this tetrahedron.

Local Function DrawTetWithPlane()

This function calculates triangle vertices for an isoquant surface in a linear tetrahedron, using the whichplane information supplied by the routine calling this one, and "draws" them using storetri(). This is really an internal function, not intended to be called by user programs. It is used by DrawTet() and DrawHex().


static inline int DrawTetWithPlane ( PetscScalar x0, PetscScalar y0, PetscScalar z0, PetscScalar f0, PetscScalar x1, PetscScalar y1, PetscScalar z1, PetscScalar f1, PetscScalar x2, PetscScalar y2, PetscScalar z2, PetscScalar f2, PetscScalar x3, PetscScalar y3, PetscScalar z3, PetscScalar f3, PetscScalar isoquant, PetscScalar edge0, PetscScalar edge1, PetscScalar edge3, int whichplane, PetscScalar* color )


int DrawTetWithPlane Returns 0 or an error code. PetscScalar x0 X-coordinate of vertex 0. PetscScalar y0 Y-coordinate of vertex 0. PetscScalar z0 Z-coordinate of vertex 0. PetscScalar f0 Function value at vertex 0. PetscScalar x1 X-coordinate of vertex 1. PetscScalar y1 Y-coordinate of vertex 1. PetscScalar z1 Z-coordinate of vertex 1. PetscScalar f1 Function value at vertex 1. PetscScalar x2 X-coordinate of vertex 2. PetscScalar y2 Y-coordinate of vertex 2. PetscScalar z2 Z-coordinate of vertex 2. PetscScalar f2 Function value at vertex 2. PetscScalar x3 X-coordinate of vertex 3. PetscScalar y3 Y-coordinate of vertex 3. PetscScalar z3 Z-coordinate of vertex 3. PetscScalar f3 Function value at vertex 3. PetscScalar isoquant Function value at which to draw triangle. PetscScalar edge0 Normalized intercept at edge 0, 0. at node 0, 1. at node 1. PetscScalar edge1 Normalized intercept at edge 1, 0. at node 1, 1. at node 2. PetscScalar edge3 Normalized intercept at edge 3, 0. at node 0, 1. at node 3. int whichplane Index of which edge intercept(s) is between zero and 1. PetscScalar* color R,G,B,A quad for this tetrahedron.

Local Function storetri()

This little inline routine just implements triangle storage. Maybe it will be more sophisticated in the future.


static inline int storetri ( PetscScalar x0, PetscScalar y0, PetscScalar z0, PetscScalar x1, PetscScalar y1, PetscScalar z1, PetscScalar x2, PetscScalar y2, PetscScalar z2, PetscScalar* color )


int storetri Returns 0 or an error code. PetscScalar x0 X-coordinate of corner 0. PetscScalar y0 Y-coordinate of corner 0. PetscScalar z0 Z-coordinate of corner 0. PetscScalar x1 X-coordinate of corner 1. PetscScalar y1 Y-coordinate of corner 1. PetscScalar z1 Z-coordinate of corner 1. PetscScalar x2 X-coordinate of corner 2. PetscScalar y2 Y-coordinate of corner 2. PetscScalar z2 Z-coordinate of corner 2. PetscScalar* color R,G,B,A quad for this triangle.

@.5  File render.c

RCS Header: /cvsroot/petscgraphics/render.c,v 1.5 2004/08/17 15:05:56 hazelsct Exp




This file contains the rendering code for Illuminator, which renders 2-D or 3-D data into an RGB(A) unsigned char array (using perspective in 3-D).

Included Files

#include "illuminator.h"illuminator.h
 #include </usr/lib/petsc/include/petscda.h>
 #include </usr/include/glib-2.0/glib.h>


Preprocessor definitions

#define __FUNCT__ "pseudocolor"


#define __FUNCT__ "pseudohueintcolor"


#define __FUNCT__ "pseudoternarycolor"


#define __FUNCT__ "render_rgb_local_2d"

@.5.1  Functions

Global Function render_rgb_local_2d()

Render data from global_array into local part of an RGB buffer. When running in parallel, these local buffers should be collected and layered to produce the full image.


int render_rgb_local_2d ( guchar* rgb, int rwidth, int rheight, int bytes_per_pixel, PetscScalar* global_array, int num_fields, int display_field, field_plot_type fieldtype, PetscScalar* minmax, int nx, int ny, int xs, int ys, int xm, int ym )


int render_rgb_local_2d Returns zero or an error code. guchar* rgb RGB buffer in which to render. int rwidth Total width of the RGB buffer. int rheight Total height of the RGB buffer. int bytes_per_pixel Number of bytes per pixel in this RGB buffer (typically 3 or 4). PetscScalar* global_array Local array of global vector data to render. int num_fields Number of field variables in the array. int display_field The (first) field we are rendering now. field_plot_type fieldtype The type of this field. PetscScalar* minmax Array of minimum and maximum values to pass to the various pseudocolor functions; if NULL, call minmax_scale to determine those values. int nx Width of the array. int ny Height of the array. int xs Starting x-coordinate of the local part of the global vector. int ys Starting y-coordinate of the local part of the global vector. int xm Width of the local part of the global vector. int ym Height of the local part of the global vector.

Global Function render_rgb_local_3d()

Render triangle data into an RGB buffer. When called in parallel, the resulting images should be layered to give the complete picture. Zooming is done by adjusting the ratio of the dir vector to the right vector.


int render_rgb_local_3d ( guchar* rgb, int rwidth, int rheight, int bytes_per_pixel, int num_triangles, PetscScalar* vertices, PetscScalar* eye, PetscScalar* dir, PetscScalar* right )


int render_rgb_local_3d Returns zero or an error code. guchar* rgb RGB buffer in which to render. int rwidth Total width of the RGB buffer. int rheight Total height of the RGB buffer. int bytes_per_pixel Number of bytes per pixel in this RGB buffer (typically 3 or 4). int num_triangles Number of triangles to render. PetscScalar* vertices Table of coordinates (x1,y1,z1, x2,y2,z2, x3,y3,z3) and colors (RGBA 0-1) making thirteen values per triangle. PetscScalar* eye Point from where we're looking (x,y,z). PetscScalar* dir Direction we're looking (x,y,z). PetscScalar* right Rightward direction in physical space (x,y,z).

Local Function pseudocolor()

This little function converts a scalar value into an rgb color from red to blue.


static inline void pseudocolor ( PetscScalar val, PetscScalar* minmax, guchar* pixel )


PetscScalar val Value to convert. PetscScalar* minmax Array with minimum and maximum values in which to scale val. guchar* pixel Address in rgb buffer where this pixel should be painted.

Local Function pseudohueintcolor()

This little function converts a vector into an rgb color with hue indicating direction (green, yellow, red, blue at 0, 90, 180, 270 degrees) and intensity indicating magnitude relative to reference magnitude in minmax[1].


static inline void pseudohueintcolor ( PetscScalar vx, PetscScalar vy, PetscScalar* minmax, guchar* pixel )


PetscScalar vx Vector's x-component.

PetscScalar vy Vector's y-component.

PetscScalar* minmax Array whose second entry has the reference magnitude. guchar* pixel Address in rgb buffer where this pixel should be painted.

Local Function pseudoternarycolor()

This little function converts two ternary fractions into an rgb color, with yellow, cyan and magenta indicating the corners.


static inline void pseudoternarycolor ( PetscScalar A, PetscScalar B, PetscScalar* minmax, guchar* pixel )


PetscScalar A First ternary fraction. PetscScalar B Second ternary fraction. PetscScalar* minmax Array first and second ternary fractions of each of the three corner values for scaling. guchar* pixel Address in rgb buffer where this pixel should be painted.

@.6  File utility.c

RCS Header: /cvsroot/petscgraphics/utility.c,v 1.1 2004/08/17 15:05:42 hazelsct Exp




This file contains small utility functions for various aspects of visualization and storage.

Included Files

#include "config.h"config.h



#include "illuminator.h"illuminator.h
 #include </usr/lib/petsc/include/petscda.h>
 #include </usr/include/glib-2.0/glib.h>


Preprocessor definitions

#define __FUNCT__ "minmax_scale"


#define __FUNCT__ "field_indices"

@.6.1  Functions

Global Function field_indices()

Given an array of field_plot_type enums, fill (part of) the indices array with integers pointing to the true variable starts. For example, in 2-D with a vector field (two fields), a scalar field (one field), a symmetric tensor field (three fields) and a ternary composition field (two fields) for a total of 8 fields, this will fill the indices array with the values 0, 2, 3, 6 and pad the rest of indices with -1, indicating when those true field variables start in the overall set of field variables.


void field_indices ( int nfields, int ds, field_plot_type* plottypes, int* indices )


int nfields Total number of fields. int ds Dimensionality of the space (used to determine the number of fields used for a vector or tensor field). field_plot_type* plottypes Array of field_plot_type enums with length nfields.

int* indices Array to hold the return values.

Global Function minmax_scale()

Determine a sensible scale for plotting, returned in *minmax. If a scalar field, returns the minimum and maximum; if a vector field, returns the minimum and maximum magnitudes (in 1-D, just plain minimum and maximum); if a ternary, returns the corners of the smallest equilateral triangle in ternary space in which all of the data fit.


int minmax_scale ( PetscScalar* global_array, int points, int num_fields, int display_field, field_plot_type fieldtype, int dimensions, PetscScalar* minmax )


int minmax_scale Returns zero or an error code. PetscScalar* global_array Array with values to scan for scale. int points Number of points in array to scan. int num_fields Number of fields in array. int display_field This display field (at least the start). field_plot_type fieldtype Type of field. int dimensions Number of dimensions. PetscScalar* minmax Array in which to return the minimum/maximum values.

@.7  File illumulti.c

RCS Header: /cvsroot/petscgraphics/illumulti.c,v 1.27 2004/06/30 15:38:18 hazelsct Exp




This file contains the functions IlluMultiSave(), IlluMultiLoad() and IlluMultiRead() designed to handle distributed storage and retrieval of data on local drives of machines in a Beowulf cluster. This should allow rapid loading of timestep data for "playback" from what is essentially a giant RAID-0 array of distributed disks, at enormously higher speeds than via NFS from a hard drive or RAID array on the head node. The danger of course is that if one node's disk goes down, you don't have a valid data set any more, but that's the nature of RAID-0, right?

The filenames saved are: If one were saving timesteps, one might include a timestep number in the basename, and also timestep and simulation time in the metadata. The metadata can also hold simulation parameters, etc.

This supports 1-D, 2-D and 3-D distributed arrays. As an extra feature, you can load a multi-CPU distributed array scattered over lots of files into a single CPU, to facilitate certain modes of data visualization.

Included Files

#include "illuminator.h"illuminator.h
 #include </usr/lib/petsc/include/petscda.h>
 #include </usr/include/glib-2.0/glib.h>



#include </usr/include/glib-2.0/glib.h>



#include </usr/lib/petsc/include/petscblaslapack.h>



#include </usr/include/libxml2/libxml/tree.h>



#include </usr/include/libxml2/libxml/parser.h>



#include <stdio.h>



#include <string.h>



#include <stdlib.h>


Preprocessor definitions

#define DPRINTF( fmt, args... )


#define __FUNCT__ "IlluMultiParseXML"


#define __FUNCT__ "IlluMultiParseData"


#define __FUNCT__ "IlluMultiStoreXML"


#define __FUNCT__ "IlluMultiStoreData"


#define __FUNCT__ "checkagree"


#define __FUNCT__ "IlluMultiRead"


#define __FUNCT__ "IlluMultiLoad"


#define __FUNCT__ "IlluMultiSave"

@.7.1  Functions

Global Function IlluMultiLoad()

This creates a new distributed array of the appropriate size and loads the data into the vector contained in it (as retrieved by DAGetVector()). It also reads the user metadata parameters into arrays stored at the supplied pointers.


int IlluMultiLoad ( char* basename, DA* theda, PetscScalar* wx, PetscScalar* wy, PetscScalar* wz, field_plot_type** fieldtypes, int* usermetacount, char*** usermetanames, char*** usermetadata )


int IlluMultiLoad It returns zero or an error code. char* basename Base file name. DA* theda Pointer to a DA object (to be created by this function). PetscScalar* wx Physical overall width in the x-direction.

PetscScalar* wy Physical overall width in the y-direction.

PetscScalar* wz Physical overall width in the z-direction.

field_plot_type** fieldtypes Data (plot) types for field variables. int* usermetacount Pointer to an int where we put the number of user metadata parameters loaded. char*** usermetanames Pointer to a char ** where the loaded parameter names are stored. This is malloced by this function, so a call to free() is needed to free up its data. char*** usermetadata Pointer to a char ** where the loaded parameter strings are stored. This is malloced by this function, so a call to free() is needed to free up its data.


First it gets the parameters from the XML file.

Next it creates a distributed array based on those parameters, and sets the names of its fields.

Then it streams the data into the distributed array's vector in one big slurp.

Global Function IlluMultiRead()

This reads the data into an existing distributed array and vector, checking that the sizes are right etc.


int IlluMultiRead ( DA theda, Vec X, char* basename, int* usermetacount, char*** usermetanames, char*** usermetadata )


int IlluMultiRead It returns zero or an error code. DA theda Distributed array object controlling the data to read. Vec X Vector into which to read the data. char* basename Base file name. int* usermetacount Pointer to an int where we put the number of user metadata parameters loaded. char*** usermetanames Pointer to a char ** where the loaded parameter names are stored. This is malloced by this function, so a call to free() is needed to free up its data. char*** usermetadata Pointer to a char ** where the loaded parameter strings are stored. This is malloced by this function, so a call to free() is needed to free up its data.


First it gets the properties of the distributed array for comparison with the metadata.

Next it parses the XML metadata file into the document tree, and reads its content into the appropriate structures, comparing parameters with those of the existing distributed array structure.

Then it streams in the data in one big slurp.

Global Function IlluMultiSave()

This saves the vector X in multiple files, two per process. Note the use of PETSC_COMM_WORLD, that will have to be corrected if somebody wants a different communicator (maybe get it from the DA?).


int IlluMultiSave ( DA theda, Vec X, char* basename, PetscScalar wx, PetscScalar wy, PetscScalar wz, field_plot_type* fieldtypes, int usermetacount, char** usermetanames, char** usermetadata, int compressed )


int IlluMultiSave it returns zero or an error code. DA theda Distributed array object controlling data saved. Vec X Vector whose data are actually being saved. char* basename Base file name. PetscScalar wx PetscScalar wy PetscScalar wz field_plot_type* fieldtypes int usermetacount Number of user metadata parameters. char** usermetanames User metadata parameter names. char** usermetadata User metadata parameter strings. int compressed Data compression: if zero then no compression (fastest), 1-9 then gzip compression level, 10-15 then gzip --best. If 16-31 then save guint32s representing relative values between min and max for each field, compressed according to this value minus 16. Likewise for 32-47 and guint16s, and 48-63 for guint8s. Yes, these alternative formats lose information and can't be used for accurate checkpointing, but they should retain enough data for visualization (except perhaps for the guint8s, which are possibly acceptable for vectors but certainly not contours).


First a check to verify a supported value of compressed, but no fancy guint* compression for complex!

Then get the distributed array parameters and processor number, and store all this data in the XML .meta file.

Finally, the data just stream out to the data file or gzip pipe in one big lump.

Local Function IlluMultiParseData()

This function reads in the data stored by IlluMultiStoreData(), complete with int/gzip compression.


static int IlluMultiParseData ( PetscScalar* globalarray, char* basename, int rank, int compressed, int gridpoints, int dof, int wrongendian, PetscScalar* fieldmin, PetscScalar* fieldmax )


int IlluMultiParseData It returns zero or an error code. PetscScalar* globalarray Array into which to load the (local) data. char* basename Base file name. int rank CPU number to read data for. int compressed Data compression: if zero then no compression (fastest), 1-9 then gzip compression level, 10-15 then gzip --best. If 16-31 then save guint32s representing relative values between min and max for each field, compressed according to this value minus 16. Likewise for 32-47 and guint16s, and 48-63 for guint8s. Yes, these alternative formats lose information and can't be used for accurate checkpointing, but they should retain enough data for visualization (except perhaps for the guint8s, which are possibly acceptable for vectors but likely not contours). int gridpoints Number of gridpoints to read data for. int dof Degrees of freedom at each node, a.k.a. number of field variables. int wrongendian Tells whether the data are stored in the opposite endian format from this platform, and thus must be switched when the data are streamed in. PetscScalar* fieldmin Minimum value of each field variable. PetscScalar* fieldmax Maximum value of each field variable.

Local Function IlluMultiParseXML()

This function reads in the XML metadata document and returns the various parameter values in the addresses pointed to by the arguments. It is called by IlluMultiLoad() and IlluMultiRead().


static int IlluMultiParseXML ( char* basename, int rank, int* compressed, int* wrongendian, int* dim, int* px, int* py, int* pz, int* nx, int* ny, int* nz, PetscScalar* wx, PetscScalar* wy, PetscScalar* wz, int* xm, int* ym, int* zm, int* dof, int* sw, DAStencilType* st, DAPeriodicType* wrap, char*** fieldnames, field_plot_type** fieldtypes, PetscScalar** fieldmin, PetscScalar** fieldmax, int* usermetacount, char*** usermetanames, char*** usermetadata )


int IlluMultiParseXML It returns zero or an error code. char* basename Base file name. int rank CPU number to read data for. int* compressed Data compression: if zero then no compression (fastest), 1-9 then gzip compression level, 10-15 then gzip --best. If 16-31 then save guint32s representing relative values between min and max for each field, compressed according to this value minus 16. Likewise for 32-47 and guint16s, and 48-63 for guint8s. Yes, these alternative formats lose information and can't be used for accurate checkpointing, but they should retain enough data for visualization (except perhaps for the guint8s, which are possibly acceptable for vectors but likely not contours). int* wrongendian Tells whether the data are stored in the opposite endian format from this platform, and thus must be switched when the data are streamed in. int* dim Dimensionality of the space. int* px Number of processors in the x-direction.

int* py Number of processors in the y-direction.

int* pz Number of processors in the z-direction.

int* nx Number of grid points over the entire array in the x-direction.

int* ny Number of grid points over the entire array in the y-direction.

int* nz Number of grid points over the entire array in the z-direction.

PetscScalar* wx Physical overall width in the x-direction, PETSC_NULL if not needed.

PetscScalar* wy Physical overall width in the y-direction, PETSC_NULL if not needed.

PetscScalar* wz Physical overall width in the z-direction, PETSC_NULL if not needed.

int* xm Number of grid points over the local part of the array in the x-direction.

int* ym Number of grid points over the local part of the array in the y-direction.

int* zm Number of grid points over the local part of the array in the z-direction.

int* dof Degrees of freedom at each node, a.k.a. number of field variables. int* sw Stencil width. DAStencilType* st Stencil type, given by the PETSc enum values.

DAPeriodicType* wrap Periodic type, given by the PETSc enum values.

char*** fieldnames Names of the field variables. field_plot_type** fieldtypes Data (plot) types for field variables, PETSC_NULL if not needed.

PetscScalar** fieldmin Minimum value of each field variable. PetscScalar** fieldmax Maximum value of each field variable. int* usermetacount Number of user metadata parameters. char*** usermetanames User metadata parameter names. char*** usermetadata User metadata parameter strings.


For GlobalSize, since there's no *size attribute (for an 0.1 version document), assume 1.

If the type attribute is missing from the Field node (as it is in version 0.1 documents), assume FIELD_SCALAR.

Local Function IlluMultiStoreData()

This function stores the data file.


static int IlluMultiStoreData ( PetscScalar* globalarray, char* basename, int rank, int compressed, int gridpoints, int dof, PetscScalar* fieldmin, PetscScalar* fieldmax )


int IlluMultiStoreData It returns zero or an error code. PetscScalar* globalarray Array from which to save the (local) data. char* basename Base file name. int rank CPU number to read data for. int compressed Data compression: if zero then no compression (fastest), 1-9 then gzip compression level, 10-15 then gzip --best. If 16-31 then save guint32s representing relative values between min and max for each field, compressed according to this value minus 16. Likewise for 32-47 and guint16s, and 48-63 for guint8s. Yes, these alternative formats lose information and can't be used for accurate checkpointing, but they should retain enough data for visualization (except perhaps for the guint8s, which are possibly acceptable for vectors but likely not contours). int gridpoints Number of gridpoints to store data for. int dof Degrees of freedom at each node, a.k.a. number of field variables. PetscScalar* fieldmin Minimum value of each field variable. PetscScalar* fieldmax Maximum value of each field variable.

Local Function IlluMultiStoreXML()

This function opens, stores and closes the XML metadata file for IlluMulti format storage. It is called by IlluMultiSave().


static int IlluMultiStoreXML ( char* basename, int rank, int compressed, int dim, int px, int py, int pz, int nx, int ny, int nz, PetscScalar wx, PetscScalar wy, PetscScalar wz, int xm, int ym, int zm, int dof, int sw, int st, int wrap, char** fieldnames, field_plot_type* fieldtypes, PetscReal* fieldmin, PetscReal* fieldmax, int usermetacount, char** usermetanames, char** usermetadata )


int IlluMultiStoreXML It returns zero or an error code. char* basename Base file name. int rank CPU number to store data for. int compressed Data compression: if zero then no compression (fastest), 1-9 then gzip compression level, 10-15 then gzip --best. If 16-31 then save guint32s representing relative values between min and max for each field, compressed according to this value minus 16. Likewise for 32-47 and guint16s, and 48-63 for guint8s. Yes, these alternative formats lose information and can't be used for accurate checkpointing, but they should retain enough data for visualization (except perhaps for the guint8s, which are possibly acceptable for vectors but certainly not contours). int dim Dimensionality of the space. int px Number of processors in the x-direction.

int py Number of processors in the y-direction.

int pz Number of processors in the z-direction.

int nx Number of grid points over the entire array in the x-direction.

int ny Number of grid points over the entire array in the y-direction.

int nz Number of grid points over the entire array in the z-direction.

PetscScalar wx Physical overall width in the x-direction.

PetscScalar wy Physical overall width in the y-direction.

PetscScalar wz Physical overall width in the z-direction.

int xm Number of grid points over the local part of the array in the x-direction.

int ym Number of grid points over the local part of the array in the y-direction.

int zm Number of grid points over the local part of the array in the z-direction.

int dof Degrees of freedom at each node, a.k.a. number of field variables. int sw Stencil width. int st Stencil type, given by the PETSc enum values.

int wrap Periodic type, given by the PETSc enum values.

char** fieldnames Names of the field variables. field_plot_type* fieldtypes Data (plot) types for field variables. PetscReal* fieldmin Minimum value of each field variable. PetscReal* fieldmax Maximum value of each field variable. int usermetacount Number of user metadata parameters. char** usermetanames User metadata parameter names. char** usermetadata User metadata parameter strings.


The XML tags in the .meta file consist of:
IlluMulti Primary tag, with attributes version,
  endian (big or little) and compression
  (none, 1-9, best, float*, long*, short* or char*1).
GlobalCPUs Number of CPUs in each direction, with
  attributes dimensions, xwidth, ywidth and zwidth
GlobalSize Size of the entire distributed array, with
  attributes xwidth, ywidth, zwidth, xsize**, ysize**, zsize** and fields
LocalSize Size of the entire local part of the array,
  with attributes xwidth, ywidth and zwidth
Stencil Stencil and periodic data, with attributes
  width, type and periodic (using PETSc enum values)
Field Data on each field, attributes name, type**, min and max
User User parameters, attributes name and value
*Lossy compression to smaller data types.

**Represents new attribute for IlluMulti 0.2 file format.

Local Function checkagree()

Ancillary routine for IlluMultiRead(): checks agreement of parameters and reports disagreement if necessary.


static inline int checkagree ( int da, int file, char* parameter )


int checkagree Returns 0 if they agree, 1 otherwise. int da Integer parameter from the existing DA. int file Integer parameter read from the file. char* parameter Parameter name for reporting.

@.8  File petsc.c

RCS Header: /cvsroot/petscgraphics/petsc.c,v 1.12 2004/07/02 20:51:08 hazelsct Exp




This is the petsc.c main file. It has all of the PETSc-dependent functions.

Included Files

#include </usr/lib/petsc/include/petscda.h>



#include "config.h"config.h



#include "illuminator.h"illuminator.h
 #include </usr/lib/petsc/include/petscda.h>
 #include </usr/include/glib-2.0/glib.h>


Preprocessor definitions

#define __FUNCT__ "DATriangulateRange"


#define __FUNCT__ "DATriangulateLocalRange"


#define __FUNCT__ "IllErrorHandler"

@.8.1  Variables

External Variables

num_triangles

extern int num_triangles

@.8.2  Functions

Global Function DATriangulateLocalRange()

Calculate vertices of isoquant triangles in a 3-D distributed array. This takes a PETSc DA object, does some sanity checks, calculates array sizes, and then gets array and passes it to Draw3DBlock for triangulation.


int DATriangulateLocalRange ( DA theda, Vec localX, int this, PetscScalar* minmax, int n_quants, PetscScalar* isoquants, PetscScalar* colors, int xmin, int xmax, int ymin, int ymax, int zmin, int zmax )


int DATriangulateLocalRange Returns 0 or an error code. DA theda The PETSc distributed array object. Vec localX PETSc local vector object associated with the DA with data we'd like to graph. int this Index of the field we'd like to draw. PetscScalar* minmax Position of block corners: xmin, xmax, ymin, ymax, zmin, zmax. int n_quants Number of isoquant surfaces to draw (isoquant values). Note PETSC_DECIDE is not a valid option here, because it's impossible to know the global maximum and minimum and have consistent contours without user-supplied information. PetscScalar* isoquants Array of function values at which to draw isoquants. PetscScalar* colors Array of color R,G,B,A quads for each isoquant. int xmin Smallest grid x-coordinate to render. int xmax Largest grid x-coordinate to render, -1 goes to full x maximum, -2 in periodic systems goes to one short of x maximum. int ymin Smallest grid y-coordinate to render. int ymax Largest grid y-coordinate to render, -1 goes to full y maximum, -2 in periodic systems goes to one short of y maximum. int zmin Smallest grid z-coordinate to render. int zmax Largest grid z-coordinate to render, -1 goes to full z maximum, -2 in periodic systems goes to one short of z maximum.

Global Function DATriangulateRange()

Calculate vertices of isoquant triangles in a 3-D distributed array. This takes a PETSc DA object, does some sanity checks, calculates array sizes, gets the local vector and array, and then calls DATriangulateLocal() to do the rest. Note that global array access (i.e. this function) is necessary for using default isoquant values, since we need to be able to calculate the maximum and minimum on the global array.


int DATriangulateRange ( DA theda, Vec globalX, int this, PetscScalar* minmax, int n_quants, PetscScalar* isoquants, PetscScalar* colors, int xmin, int xmax, int ymin, int ymax, int zmin, int zmax )


int DATriangulateRange Returns 0 or an error code. DA theda The PETSc distributed array object. Vec globalX PETSc global vector object associated with the DA with data we'd like to graph. int this Index of the field we'd like to draw. PetscScalar* minmax Position of block corners: xmin, xmax, ymin, ymax, zmin, zmax. int n_quants Number of isoquant surfaces to draw (isoquant values), or PETSC_DECIDE to use red, yellow, green, blue at 0.2, 0.4, 0.6 and 0.8 between the vector's global minimum and maximum values. PetscScalar* isoquants Array of function values at which to draw isoquants, or PETSC_NULL if n_quants=PETSC_DECIDE.

PetscScalar* colors Array of color R,G,B,A quads for each isoquant, or PETSC_NULL if n_quants=PETSC_DECIDE.

int xmin Smallest grid x-coordinate to render. int xmax Largest grid x-coordinate to render, -1 goes to full x maximum, -2 in periodic systems goes to one short of x maximum. int ymin Smallest grid y-coordinate to render. int ymax Largest grid y-coordinate to render, -1 goes to full y maximum, -2 in periodic systems goes to one short of y maximum. int zmin Smallest grid z-coordinate to render. int zmax Largest grid z-coordinate to render, -1 goes to full z maximum, -2 in periodic systems goes to one short of z maximum.

Global Function IllErrorHandler()

Handle errors, in this case the PETSc way.


int IllErrorHandler ( int id, char* message )


int IllErrorHandler Returns the error code supplied. int id Index of the error, defined in petscerror.h. char* message Text of the error message.

@.9  File geomview.c

RCS Header: /cvsroot/petscgraphics/geomview.c,v 1.6 2003/04/30 19:34:55 hazelsct Exp




This file has the Geomview interface, including the PETSc vector gather operations to bring everything to CPU 0.

Included Files

#include <stdio.h>



#include </usr/lib/petsc/include/petscvec.h>



#include "config.h"config.h



#include "illuminator.h"illuminator.h
 #include </usr/lib/petsc/include/petscda.h>
 #include </usr/include/glib-2.0/glib.h>


Preprocessor definitions

#define DPRINTF( fmt, args... )


#define __FUNCT__ "GeomviewBegin"


#define __FUNCT__ "GeomviewEnd"


#define __FUNCT__ "GeomviewDisplayTriangulation"

@.9.1  Variables

External Variables

num_triangles

Declared in illuminator.c, this gives the current number of triangles on this node.


extern int num_triangles


vertices

Declared in illuminator.c, this array stores the corner coordinates and color information for each triangle.


extern PetscScalar vertices[]

Local Variables

pfd

Stream holding the pipe to the Geomview process. It is initialized to NULL, then set by GeomviewBegin, and cleared by GeomviewEnd. This can be used as a flag to determine whether the Geomview display is open.


static FILE* pfd

@.9.2  Functions

Global Function GeomviewBegin()

Spawn a new geomview process. Most of this was shamelessly ripped from Ken Brakke's Surface Evolver.


int GeomviewBegin ( MPI_Comm comm )


int GeomviewBegin Returns 0 or an error code. MPI_Comm comm MPI communicator for rank information, if NULL it uses PETSC_COMM_WORLD.

Global Function GeomviewDisplayTriangulation()

Pipe the current triangulation to Geomview for display. Much of this is based on Ken Brakke's Surface Evolver.


int GeomviewDisplayTriangulation ( MPI_Comm comm, PetscScalar* minmax, char* name, PetscTruth transparent )


int GeomviewDisplayTriangulation Returns 0 or an error code. MPI_Comm comm MPI communicator for rank information, if NULL it uses PETSC_COMM_WORLD. PetscScalar* minmax Position of block corners: xmin, xmax, ymin, ymax, zmin, zmax. char* name Name to give the Geomview OOGL object which we create. PetscTruth transparent Geomview transparency flag.


First, this creates global and local vectors for all of the triangle vertices.

It then gathers (``scatters'') all vertex data to processor zero,

and puts them in an array.

Finally, it sends everything to Geomview,

and cleans up the mess, resetting the number of triangles to zero.

Global Function GeomviewEnd()

Exit the current running Geomview process and close its pipe. Based in part on Ken Brakke's Surface Evolver.


int GeomviewEnd ( MPI_Comm comm )


int GeomviewEnd Returns 0 or an error code. MPI_Comm comm MPI communicator for rank information, if NULL it uses PETSC_COMM_WORLD.

@.10  File tsview.c

RCS Header: /cvsroot/petscgraphics/tsview.c,v 1.35 2004/07/02 20:50:41 hazelsct Exp




This program views the output of a time series saved using IlluMultiSave(). It basically just switches between timesteps; future versions may be more interesting. The neat part of it is that it loads multiprocessor data and displays it on a single CPU.

Included Files

#include "illuminator.h"illuminator.h
 #include </usr/lib/petsc/include/petscda.h>
 #include </usr/include/glib-2.0/glib.h>



#include <sys/dir.h>



#include <libgen.h>



#include <string.h>



#include <stdlib.h>



#include <term.h>



#include <readline/readline.h>



#include <readline/history.h>


Preprocessor definitions

#define HELP_STRING "tsview commands:\n <enter> Display next timestep\n b Display previous timestep\n i increment Set the next timestep increment\n ### Jump to timestep ###\n t Toggle Geomview transparency (3-D only)\n v Change field displayed (3-D only)\n p [v1 v2 ...] Set contour values for plotting or \"auto\" (3-D only)\n r Reloads entries in a directory\n s size Set maximum dimension of PETSc viewer windows (2-D only)\n cx, cy, cz Toggle xcut, ycut, zcut (cut last row/plane of periodic DA)\n gx30-90, y,z Set plot x range to 30-90, same for y and z\n h/? Print this information\n q/x Quit tsview\n"


#define DPRINTF( fmt, args... )


#define __FUNCT__ "myfilter"


#define __FUNCT__ "main"

@.10.1  Variables

Variable basefilename

char* basefilename

Local Variables

help

static char help[]


line_read

Functions for reading the command line and avoiding reading empty lines

Probably this function is not Petsc safe, but we'll see.


static char* line_read

@.10.2  Functions

Global Function PetscSynchronizedFReadline()

int PetscSynchronizedFReadline ( MPI_Comm comm, char* message, char* string )

Global Function main()

This is main().


int main ( int argc, char* argv[] )


int main It returns an int to the OS. int argc Argument count. char* argv[] Arguments.


After PETSc initialization, it gets the list of files matching the basename.

In the main loop, the various timesteps are displayed, with options: The Illuminator-based 3-D viewer can only display one field at a time. At the beginning, that is field 0, and is cycled using the v command.

Global Function myfilter()

This function returns non-zero for "qualifying" file names which start with the stored files' basename and end with .cpu0000.meta. It is used as the select() function for scandir() in main().


int myfilter ( const struct dirent* direntry )


int myfilter Returns non-zero for qualifying filenames. const struct dirent* direntry Directory entry with filename to test.

Global Function rl_gets()

char* rl_gets ( char* message )

@.11  File tsview-ng.c

RCS Header: /cvsroot/petscgraphics/tsview-ng.c,v 1.21 2004/08/11 12:44:08 hazelsct Exp




This program views the output of a time series saved using IlluMultiSave(). It basically just switches between timesteps; future versions may be more interesting. The neat part of it is that it loads multiprocessor data and displays it on a single CPU.

Included Files

#include "illuminator.h"illuminator.h
 #include </usr/lib/petsc/include/petscda.h>
 #include </usr/include/glib-2.0/glib.h>



#include </usr/include/libglade-2.0/glade/glade.h>



#include </usr/include/libgnomeui-2.0/gnome.h>



#include </usr/include/libgnomeui-2.0/libgnomeui/libgnomeui.h>



#include <sys/dir.h>



#include <libgen.h>



#include <string.h>


Preprocessor definitions

#define DPRINTF( fmt, args... )


#define __FUNCT__ "render_dataviews"


#define __FUNCT__ "myfilter"


#define __FUNCT__ "main"

@.11.1  Variables

Variable xml

GladeXML* xml

Variable entrynum

int entrynum

Variable total_entries

int total_entries

Variable current_timestep

int current_timestep

Variable the_basename

char* the_basename

Variable basedirname

char* basedirname

Variable stepnames

char** stepnames

Variable current_time

double current_time

Variable width

int width

Variable height

int height

Variable nx

int nx

Variable ny

int ny

Variable dataview_count

int dataview_count

Variable dataviews

GtkWidget* dataviews[1]

Variable rgbbuf

guchar* rgbbuf[1]

Variable sizemag

double sizemag

Variable transp

PetscTruth transp

Variable vecmax

PetscScalar vecmax

Variable theda

DA theda

Variable global

Vec global

Variable minmax

PetscScalar minmax[6]

Variable fieldtypes

field_plot_type* fieldtypes

Variable dimensions

int dimensions

Variable num_fields

int num_fields

Variable current_field

int current_field

Variable field_index

int* field_index

Variable num_variables

int num_variables[1]

Variable variable_indices

int** variable_indices

Local Variables

help

static char help[]


basefilename

Little variable for myfilter() and refresh_stepnames().


static char* basefilename

@.11.2  Functions

Global Function change_variable()

void change_variable ( GtkWidget* widget, gpointer user_data )

Global Function display_timestep()

void display_timestep ( int usermetacount, char** usermetanames, char** usermetadata )

Global Function main()

This is main().


int main ( int argc, char* argv[] )


int main It returns an int to the OS. int argc Argument count. char* argv[] Arguments.


After PETSc and glade/GNOME initialization, it gets the list of files matching the basename.

Global Function myfilter()

This function returns non-zero for "qualifying" file names which start with the stored files' basename.time and end with .cpu0000.meta. It is used as the select() function for scandir() in main().


int myfilter ( const struct dirent* direntry )


int myfilter Returns non-zero for qualifying filenames. const struct dirent* direntry Directory entry with filename to test.

Global Function on_about_activate()

void on_about_activate ( GtkWidget* none, gpointer user_data )

Global Function on_mag_spin_value_changed()

void on_mag_spin_value_changed ( GtkWidget* mag_spin, gpointer user_data )

Global Function on_plot_area_expose_event()

void on_plot_area_expose_event ( GtkWidget* widget, GdkEventExpose* event, gpointer user_data )

Global Function on_refresh_activate()

void on_refresh_activate ( GtkWidget* none, gpointer user_data )

Global Function on_save_activate()

void on_save_activate ( GtkWidget* widget, gpointer user_data )

Global Function on_timestep_spin_value_changed()

void on_timestep_spin_value_changed ( GtkWidget* timestep_spin, gpointer user_data )

Global Function refresh_stepnames()

This loads the names of the files into a long list.


int refresh_stepnames ( void )

Global Function render_dataviews()

void render_dataviews ( void )

@.12  File 3dgf.c

RCS Header: /cvsroot/petscgraphics/3dgf.c,v 1.13 2004/03/07 01:56:18 hazelsct Exp




This is a neat 3-D graphing application of Illuminator. Just put whatever function you like down in line 110 or so (or graph the examples provided), or run with -twodee and use PETSc's native 2-D graphics (though that would be BORING!). You might want to run it as:
./3dgf -da_grid_x 50 -da_grid_y 50 -da_grid_z 50
and hit return to end.

Included Files

#include "illuminator.h"illuminator.h
 #include </usr/lib/petsc/include/petscda.h>
 #include </usr/include/glib-2.0/glib.h>


Preprocessor definitions

#define DPRINTF( fmt, args... )


#define __FUNCT__ "function_3d"


#define __FUNCT__ "function_2d"


#define __FUNCT__ "main"

@.12.1  Variables

Local Variables

help

static char help[]

@.12.2  Functions

Global Function main()

The usual main function.


int main ( int argc, char** argv )


int main Returns 0 or error. int argc Number of args. char** argv The args.


The program first calls PetscInitialize() and creates the distributed arrays. Note that even though this program doesn't do any communication between the CPUs, illuminator must do so in order to make the isoquants at CPU boundaries, so the stencil width must be at least one.

Next it gets the distributed array's local corner and global size information. It gets the global vector, and loops over the part stored on this CPU to set all of the function values, using function_3d() or function_2d() depending on whether the -twodee command line switch was used at runtime.

It then uses GeomviewBegin() or PetscViewerDrawOpen() to start the viewer, and either DATriangulate() and GeomviewDisplayTriangulation() or VecView() to display the solution.

Finally, it prompts the user to hit <return> before wrapping up.

Local Function function_2d()

This is where you put the 2-D function you'd like to graph using PETSc's native 2-D "contour" color graphics.


static inline PetscScalar function_2d ( PetscScalar x, PetscScalar y )


PetscScalar function_2d It returns the function value. PetscScalar x The x-coordinate at which to calculate the function value. PetscScalar y The y-coordinate at which to calculate the function value.

Local Function function_3d()

This is where you put the 3-D function you'd like to graph, or the 2-D function you'd like to graph in 3-D using the zero contour of f(x,y)-z.


static inline PetscScalar function_3d ( PetscScalar x, PetscScalar y, PetscScalar z )


PetscScalar function_3d It returns the function value. PetscScalar x The x-coordinate at which to calculate the function value. PetscScalar y The y-coordinate at which to calculate the function value. PetscScalar z The z-coordinate at which to calculate the function value.

@.13  File chts.c

RCS Header: /cvsroot/petscgraphics/chts.c,v 1.28 2004/06/30 15:38:17 hazelsct Exp




This is the Cahn Hilliard timestepping code. It is provided here as an example usage of the Illuminator Distributed Visualization Library.

Included Files

#include "cahnhill.h"cahnhill.h
 #include </usr/lib/petsc/include/petscts.h>
 #include </usr/lib/petsc/include/petscda.h>



#include "illuminator.h"illuminator.h
 #include </usr/lib/petsc/include/petscda.h>
 #include </usr/include/glib-2.0/glib.h>


Preprocessor definitions

#define DPRINTF( fmt, args... )


#define __FUNCT__ "ch_ts_monitor"


#define __FUNCT__ "main"


#define __FUNCT__ "FormInitialCondition"


#define __FUNCT__ "InitializeProblem"

@.13.1  Variables

Local Variables

help

static char help[]

@.13.2  Functions

Global Function FormInitialCondition()

Like it says, put together the initial condition.


int FormInitialCondition ( AppCtx* user, Vec X )


int FormInitialCondition Returns zero or error. AppCtx* user The user context structure. Vec X Vector in which to place the initial condition.

Global Function InitializeProblem()

This takes the gory details of initialization out of the way (importing parameters into the user context, etc.).


int InitializeProblem ( AppCtx* user, Vec* xvec )


int InitializeProblem Returns zero or error. AppCtx* user The user context to fill. Vec* xvec Vector into which to put the initial condition.

Global Function ch_ts_jacobian_2d()

Wrapper for ch_jacobian_2d() in cahnhill.c.


int ch_ts_jacobian_2d ( TS thets, PetscScalar time, Vec X, Mat* A, Mat* B, MatStructure* flag, void* ptr )


int ch_ts_jacobian_2d Usual return: zero or error. TS thets Timestepping context, ignored here. PetscScalar time Current time, also ignored. Vec X Current solution vector. Mat* A Place to put the new Jacobian. Mat* B Place to put the new conditioning matrix. MatStructure* flag Flag describing the volatility of the structure. void* ptr User data pointer.

Global Function ch_ts_jacobian_3d()

Wrapper for ch_jacobian_3d() in cahnhill.c.


int ch_ts_jacobian_3d ( TS thets, PetscScalar time, Vec X, Mat* A, Mat* B, MatStructure* flag, void* ptr )


int ch_ts_jacobian_3d Usual return: zero or error. TS thets Timestepping context, ignored here. PetscScalar time Current time, also ignored. Vec X Current solution vector. Mat* A Place to put the new Jacobian. Mat* B Place to put the new conditioning matrix. MatStructure* flag Flag describing the volatility of the structure. void* ptr User data pointer.

Global Function ch_ts_monitor()

Monitor routine which displays the current state, using Illuminator's geomview front-end (unless -no_contours is used); and also saves it using IlluMultiSave() if -save_data is specified.


int ch_ts_monitor ( TS thets, int stepno, PetscScalar time, Vec X, void* ptr )


int ch_ts_monitor Usual return: zero or error. TS thets Timestepping context, ignored here. int stepno Current time step number. PetscScalar time Current time. Vec X Vector of current solved field values. void* ptr User data pointer.

Global Function ch_ts_residual_vector_2d()

Wrapper for ch_residual_vector_2d() in cahnhill.c.


int ch_ts_residual_vector_2d ( TS thets, PetscScalar time, Vec X, Vec F, void* ptr )


int ch_ts_residual_vector_2d Usual return: zero or error. TS thets Timestepping context, ignored here. PetscScalar time Current time, also ignored. Vec X Current solution vector. Vec F Function vector to return. void* ptr User data pointer.

Global Function ch_ts_residual_vector_3d()

Wrapper for ch_residual_vector_3d() in cahnhill.c.


int ch_ts_residual_vector_3d ( TS thets, PetscScalar time, Vec X, Vec F, void* ptr )


int ch_ts_residual_vector_3d Usual return: zero or error. TS thets Timestepping context, ignored here. PetscScalar time Current time, also ignored. Vec X Current solution vector. Vec F Function vector to return. void* ptr User data pointer.

Global Function main()

The usual main function.


int main ( int argc, char** argv )


int main Returns 0 or error. int argc Number of args. char** argv The args.

@.14  File cahnhill.c

RCS Header: /cvsroot/petscgraphics/cahnhill.c,v 1.8 2003/05/21 22:52:29 hazelsct Exp




This file contains the heart of the Cahn-Hilliard formulation, in particular the functions which build the finite difference residuals and Jacobian.

Included Files

#include "cahnhill.h"cahnhill.h
 #include </usr/lib/petsc/include/petscts.h>
 #include </usr/lib/petsc/include/petscda.h>


Preprocessor definitions

#define PSIPRIME_FLOPS 5


#define PSIDOUBLEPRIME_FLOPS 8


#define RESIDUAL_FLOPS_2D


#define RESIDUAL_FLOPS_3D

@.14.1  Functions

Global Function ch_jacobian_2d()

This computes the Jacobian matrix at each iteration, starting with the alpha term which is pre-computed at the beginning by ch_jacobian_alpha_2d().


int ch_jacobian_2d ( Vec X, Mat* A, Mat* B, MatStructure* flag, void* ptr )


int ch_jacobian_2d It returns 0 or an error code. Vec X The vector of unknowns. Mat* A The Jacobian matrix returned to PETSc. Mat* B The matrix preconditioner, in this case the same matrix. MatStructure* flag Flag saying the nonzeroes are the same each time. void* ptr Application context structure.

Global Function ch_jacobian_3d()

This computes the Jacobian matrix at each iteration, starting with the alpha term which is pre-computed at the beginning by ch_jacobian_alpha_3d().


int ch_jacobian_3d ( Vec X, Mat* A, Mat* B, MatStructure* flag, void* ptr )


int ch_jacobian_3d It returns 0 or an error code. Vec X The vector of unknowns. Mat* A The Jacobian matrix returned to PETSc. Mat* B The matrix preconditioner, in this case the same matrix. MatStructure* flag Flag saying the nonzeroes are the same each time. void* ptr Application context structure.

Global Function ch_jacobian_alpha_2d()

This creates the initial alpha and J matrices, where alpha is the alpha term component of the Jacobian. Since the alpha term is linear, this part of the Jacobian need only be calculated once.


int ch_jacobian_alpha_2d ( AppCtx* user )


int ch_jacobian_alpha_2d It returns zero or an error message. AppCtx* user The application context structure pointer.

Global Function ch_jacobian_alpha_3d()

This creates the initial alpha and J matrices, where alpha is the alpha term component of the Jacobian. Since the alpha term is linear, this part of the Jacobian need only be calculated once.


int ch_jacobian_alpha_3d ( AppCtx* user )


int ch_jacobian_alpha_3d It returns zero or an error message. AppCtx* user The application context structure pointer.

Global Function ch_residual_vector_2d()

This evaluates the nonlinear finite difference approximation to the residuals Ri. Note that it loops on the interior points and the boundary separately, to avoid conditional statements within the double loop over the local grid indices.


int ch_residual_vector_2d ( Vec X, Vec F, void* ptr )


int ch_residual_vector_2d It returns zero or an error value. Vec X The pre-allocated local vector of unknowns. Vec F The pre-allocated local vector of residuals, filled by this function. void* ptr Data passed in the application context.

Global Function ch_residual_vector_3d()

This evaluates the nonlinear finite difference approximation to the residuals Ri. Note that it loops on the interior points and the boundary separately, to avoid conditional statements within the double loop over the local grid indices.

Thus far, only periodic boundary conditions work.


int ch_residual_vector_3d ( Vec X, Vec F, void* ptr )


int ch_residual_vector_3d It returns zero or an error value. Vec X The pre-allocated local vector of unknowns. Vec F The pre-allocated local vector of residuals, filled by this function. void* ptr Data passed in the application context.

Local Function ch_psidoubleprime()

This calculates the second derivative of homogeneous free energy with respect to concentration, for insertion into the Jacobian matrix. See the ch_psiprime() function for the definition of Y.


static inline PetscScalar ch_psidoubleprime ( PetscScalar C, PetscScalar mparam )


PetscScalar ch_psidoubleprime It returns the second derivative Y''(C).

PetscScalar C The concentration. PetscScalar mparam The model parameter m.

Local Function ch_psiprime()

This calculates the derivative of homogeneous free energy with respect to concentration, which is a component of the chemical potential. It currently uses
Y' = C(1-C) æ
ç
ç
è
1
2
+m-C ö
÷
÷
ø
which gives (meta)stable equilibria at C=0 and 1 and an unstable equilibrium at C=1/2+m; if m>0 then the 0 phase is stable and vice versa.


static inline PetscScalar ch_psiprime ( PetscScalar C, PetscScalar mparam )


PetscScalar ch_psiprime It returns the derivative itself. PetscScalar C The concentration. PetscScalar mparam The model parameter m.

Local Function ch_residual_2d()

This function computes the residual from indices to points in the concentration array. ``Up'' refers to the positive y-direction, ``down'' to negative y, ``left'' to negative x and ``right'' to positive x.


static inline PetscScalar ch_residual_2d ( PetscScalar* conc, PetscScalar alpha, PetscScalar beta, PetscScalar mparam, PetscScalar hx, PetscScalar hy, int upup, int upleft, int up, int upright, int leftleft, int left, int current, int right, int rightright, int downleft, int down, int downright, int downdown )


PetscScalar ch_residual_2d Returns the residual itself PetscScalar* conc Array of concentrations PetscScalar alpha Model parameter ka

PetscScalar beta Model parameter kb

PetscScalar mparam Model parameter m

PetscScalar hx Inverse square x-spacing hx-2

PetscScalar hy Inverse square y-spacing hy-2

int upup Index to array position two cells up from current int upleft Index to array position one cell up and one left from current int up Index to array position one cell up from current int upright Index to array position one cell up and one right from current int leftleft Index to array position two cells left of current int left Index to array position one cell left of current int current Index to current cell array position int right Index to array position one cell right of current int rightright Index to array position two cells right of current int downleft Index to array position one cell down and one left from current int down Index to array position one cell down from current int downright Index to array position one cell down and one right from current int downdown Index to array position two cells down from current


This calculates the b-term, kb times the Laplacian of Y'(C),

then subtracts the a-term, kaÑ2Ñ2C.

Local Function ch_residual_3d()

This function computes the residual from indices to points in the concentration array. ``Front refers to the positive z-direction, ``back'' to negative z, ``up'' to positive y, ``down'' to negative y, ``left'' to negative x and ``right'' to positive x.


static inline PetscScalar ch_residual_3d ( PetscScalar* conc, PetscScalar alpha, PetscScalar beta, PetscScalar mparam, PetscScalar hx, PetscScalar hy, PetscScalar hz, int frontfront, int frontup, int frontleft, int front, int frontright, int frontdown, int upup, int upleft, int up, int upright, int leftleft, int left, int current, int right, int rightright, int downleft, int down, int downright, int downdown, int backup, int backleft, int back, int backright, int backdown, int backback )


PetscScalar ch_residual_3d Returns the residual itself PetscScalar* conc Array of concentrations PetscScalar alpha Model parameter ka

PetscScalar beta Model parameter kb

PetscScalar mparam Model parameter m

PetscScalar hx Inverse square x-spacing hx-2

PetscScalar hy Inverse square y-spacing hy-2

PetscScalar hz Inverse square z-spacing hz-2

int frontfront Index to array position two cells in front of current int frontup Index to array position one cell front and one up from current int frontleft Index to array position one cell front and one left from current int front Index to array position one cell in front of current int frontright Index to array position one cell front and one right from current int frontdown Index to array position one cell front and one down from current int upup Index to array position two cells up from current int upleft Index to array position one cell up and one left from current int up Index to array position one cell up from current int upright Index to array position one cell up and one right from current int leftleft Index to array position two cells left of current int left Index to array position one cell left of current int current Index to current cell array position int right Index to array position one cell right of current int rightright Index to array position two cells right of current int downleft Index to array position one cell down and one left from current int down Index to array position one cell down from current int downright Index to array position one cell down and one right from current int downdown Index to array position two cells down from current int backup Index to array position one cell back and one up from current int backleft Index to array position one cell back and one left from current int back Index to array position one cell in back of current int backright Index to array position one cell back and one right from current int backdown Index to array position one cell back and one down from current int backback Index to array position two cells in back of current


This calculates the b-term, kb times the Laplacian of Y'(C),

then subtracts the a-term, kaÑ2Ñ2C.

@.15  File cahnhill.h

RCS Header: /cvsroot/petscgraphics/cahnhill.h,v 1.8 2002/08/29 15:08:15 hazelsct Exp




Common files for cahnhill.c and programs which use it (e.g. chts.c), based on PETSc SNES tutorial common8and9.h.

Included Files

#include </usr/lib/petsc/include/petscts.h>



#include </usr/lib/petsc/include/petscda.h>


Preprocessor definitions

#define CAHNHILL_H


#define C( i )

@.15.1  Type definitions

Typedef AppCtx

User-defined application context for chts.c - contains data needed by the application-provided callbacks: ch_residual_vector_xd() (x is 2 or 3).


typedef struct {...} AppCtx


struct
 {
 PetscTruth threedee;
 PetscScalar kappa;
 PetscScalar epsilon;
cxreftabiia  PetscScalar gamma;
 PetscScalar mparam;
 int mx;
 int my;
 int mz;
 int mc;
 int chvar;
 Vec localX;
cxreftabiia  Vec localF;
 DA da;
 int rank;
 int size;
 MPI_Comm comm;
 int ilevel;
 int nlevels;
 Vec x_old;
cxreftabiia  Mat J;
 Mat alpha;
 DAPeriodicType period;
 ISLocalToGlobalMapping isltog;
 PetscViewer theviewer;
 char** label;
 PetscTruth print_grid;
 PetscTruth print_vecs;
cxreftabiia  PetscTruth no_contours;
 PetscTruth random;
 PetscTruth save_data;
 int load_data;
 }


@.16  File chui.c

RCS Header: /cvsroot/petscgraphics/chui.c,v 1.13 2004/05/25 13:27:27 hazelsct Exp




This is a Glade front end to the little phase field/fluid structure interactions program based on PETSc, but can serve as a front end to a variety of PETSc programs with minor adjustments.

Callback functions are grouped here according to where they appear in the main window (except on_run_clicked is below main window items), then the run control dialog, and save dialog.

I haven't put function comments in to keep the line count down, the functions are generally pretty simple GTK+ callbacks.

Included Files

#include </usr/include/libglade-2.0/glade/glade.h>



#include </usr/include/libgnomeui-2.0/gnome.h>



#include </usr/include/libgnomeui-2.0/libgnomeui/libgnomeui.h>



#include <stdio.h>



#include <math.h>


Preprocessor definitions

#define DPRINTF( fmt... )


#define MAX_COMMAND_LINE_OPTIONS 22

@.16.1  Variables

Variable xml

GladeXML* xml

Variable simulation_input_file

FILE* simulation_input_file

Variable simulation_output_file

FILE* simulation_output_file

Variable Lx

double Lx

Variable nx

int nx

Variable dt

double dt

Variable dt_factor

double dt_factor

Variable dt_max

double dt_max

Variable last_tstep

int last_tstep

Variable display_x

gboolean display_x

Variable display_text

gboolean display_text

Variable remote_host

gboolean remote_host

Variable remote_hostname

const gchar* remote_hostname

Variable thetransport

gchar thetransport[50]

Variable mpirun_command

const gchar* mpirun_command

Variable number_cpus

int number_cpus

Variable twodee

gboolean twodee

Variable options_filename

gchar* options_filename

Variable pipe_input_tag

gint pipe_input_tag

Variable from_simulation_pipe

int from_simulation_pipe[2]

Variable to_simulation_pipe

int to_simulation_pipe[2]

@.16.2  Functions

Global Function main()

int main ( int argc, char* argv[] )

Global Function on_2d_activate()

void on_2d_activate ( GtkWidget* unused, gpointer user_data )

Global Function on_3d_activate()

void on_3d_activate ( GtkWidget* unused, gpointer user_data )

Global Function on_about_activate()

void on_about_activate ( GtkWidget* null_widget, gpointer user_data )

Global Function on_last_timestep_changed()

void on_last_timestep_changed ( GtkWidget* last_timestep, gpointer user_data )

Global Function on_load_ok_clicked()

void on_load_ok_clicked ( GtkWidget* load_file, gpointer user_data )

Global Function on_max_timestep_changed()

void on_max_timestep_changed ( GtkWidget* max_timestep, gpointer user_data )

Global Function on_mpirun_changed()

void on_mpirun_changed ( GtkWidget* mpirun, gpointer user_data )

Global Function on_num_cpus_changed()

void on_num_cpus_changed ( GtkWidget* num_cpus, gpointer user_data )

Global Function on_pause_clicked()

void on_pause_clicked ( GtkWidget* forgot, gpointer user_data )

Global Function on_remote_check_toggled()

void on_remote_check_toggled ( GtkWidget* remote_check, gpointer user_data )

Global Function on_remote_host_changed()

void on_remote_host_changed ( GtkWidget* remote_host, gpointer user_data )

Global Function on_resolution_changed()

void on_resolution_changed ( GtkWidget* resolution, gpointer user_data )

Global Function on_rsh_item_activate()

void on_rsh_item_activate ( GtkWidget* widget, gpointer user_data )

Global Function on_run_activate()

void on_run_activate ( GtkWidget* null_widget, gpointer user_data )

Global Function on_save_ok_clicked()

void on_save_ok_clicked ( GtkWidget* save_file, gpointer user_data )

Global Function on_show_options_activate()

void on_show_options_activate ( GtkWidget* null_widget, gpointer user_data )

Global Function on_show_options_toggled()

void on_show_options_toggled ( GtkWidget* show_options, gpointer user_data )

Global Function on_show_output_activate()

void on_show_output_activate ( GtkWidget* null_widget, gpointer user_data )

Global Function on_show_output_toggled()

void on_show_output_toggled ( GtkWidget* show_output, gpointer user_data )

Global Function on_ssh_item_activate()

void on_ssh_item_activate ( GtkWidget* widget, gpointer user_data )

Global Function on_stop_clicked()

void on_stop_clicked ( GtkWidget* output_window, gpointer user_data )

Global Function on_textdisplay_toggled()

void on_textdisplay_toggled ( GtkWidget* textdisplay, gpointer user_data )

Global Function on_time_factor_changed()

void on_time_factor_changed ( GtkWidget* time_factor, gpointer user_data )

Global Function on_timestep_changed()

void on_timestep_changed ( GtkWidget* timestep, gpointer user_data )

Global Function on_width_changed()

void on_width_changed ( GtkWidget* width, gpointer user_data )

Global Function on_xdisplay_toggled()

void on_xdisplay_toggled ( GtkWidget* xdisplay, gpointer user_data )

Global Function open_params()

void open_params ( GtkWidget* null_widget, gpointer user_data )

Global Function read_simulation_data()

void read_simulation_data ( gpointer user_data, gint source, GdkInputCondition condition )

Global Function save_params()

void save_params ( GtkWidget* null_widget, gpointer user_data )

Global Function save_params_as()

void save_params_as ( GtkWidget* null_widget, gpointer user_data )

@.17  File config.h

Preprocessor definitions

#define HAVE_DLFCN_H 1


#define HAVE_INTTYPES_H 1


#define HAVE_LIBPETSC 1


#define HAVE_MEMORY_H 1


#define HAVE_READLINE_HISTORY_H 1


#define HAVE_READLINE_READLINE_H 1


#define HAVE_STDINT_H 1


#define HAVE_STDLIB_H 1


#define HAVE_STRINGS_H 1


#define HAVE_STRING_H 1


#define HAVE_SYS_STAT_H 1


#define HAVE_SYS_TYPES_H 1


#define HAVE_UNISTD_H 1


#define PACKAGE "illuminator"


#define PACKAGE_BUGREPORT ""


#define PACKAGE_NAME ""


#define PACKAGE_STRING ""


#define PACKAGE_TARNAME ""


#define PACKAGE_VERSION ""


#define STDC_HEADERS 1


#define VERSION "0.8.9"


1
longnone, long1-long9 or longbest compresses each double to a 32-bit unsigned int, with 0 representing the minimum for that field and 232-1 representing the maximum; likewise shortnone, short1-short9, shortbest uses 16-bit unsigned ints, and char* uses 8-bit unsigned ints. float is there to indicate that PetscScalar is 4 bytes at save time, loading should adjust accordingly; that's not fully supported just yet. At some point I'll have to figure out how to represent complex.

This document was translated from LATEX by HEVEA.