This file gives a short description of the formats
recognized by xgraphic and xd3d. You'll find examples
of most of them in the directory Examples
=============================================================

I. xgraphic file format
=======================

* Ascii file with 2 coordinates x y per line.

* Commentaries can be inserted at the beginning of the file
with a # in first column (as many lines as you need).

* A blank line in the middle of the file means a jump
between 2 consecutives points.

* Multicolumn files (number of columns > 2) "à la gnuplot"
are recognized. If "toto" is the file name,

    xgraphic toto#2#5

will plot column 5 as a function of column 2

* You can also plot the graph of a function given by an equation:
type
    xgraphic #
and answer the questions. The equation must be written in fortran
synthax, i.e. using the following operators. + - * / ** sin cos etc...

Type "xgraphic -h" for more help.

=============================================================

II. xd3d file formats
=====================

1/ Meshes
---------

* Native format is "avoirND" format. The files must have the extension
.avoir2D or .avoir3D according to the space dimension (note that it is
only a facility. The file formats are the same in both dimensions).

"avoirND" files are binary. You can read them through appropriate
programs. The library lib/question_lib.a contains utilities to
read/write meshes (src/qlib/litavoir.f, src/qlib/ecritavoir.f). The
file src/include/com_avoir.f is exceptionnaly widely commented and
provides the description of all the parameters involved in routines
litavoir.f and ecritavoir.f.

In the directory src/various, the source code of clair.f (translation
of a avoirND into an ascii file) and obscur.f (the opposite) show you
how to read/write a complete avoirND. You can also have a look at
src/various/translation.f

If you don't need all the parameters of the avoirND format, but you
rather want to plot simple meshes (nodes, elements and that's all. No
references subdomains, pressures etc...), have a look at
src/various/txt2avoir.f.  It does the translation job between basic
mesh format and avoirND.

The local numbering of nodes in an element is the usual Finite Element
convention (anti-clockwise numbering for 2d P1 or Q1 elements).  The
directory Example provides reference elements for more complex types
of FE. You can visualize the node numbering with xd3d by clicking the
"num" button (menu inside).

* xd3d can also read "nopo" files (from Modulef/INRIA). For a 
description of this format, see the Modulef manual. The translation
into avoirND format is performed by the program "nopo_avoir".

2/ Fields associated to the mesh
--------------------------------

For a mesh having N nodes and NEL elements, various scalar/vector
fields are recognized. Data are red in ascii files. The first line
after an eventual commentary line (one line of commentary can be
inserted at the beginning of the file with a # in first column) is an
integer. If it is N, the following datas are attached to the nodes; if
it is NEL, xd3d understands that he reads cell data.  Other values
give an error message.

The remaining of the file is N or NEL lines, with 1 number (scalar
field) or 2 or 3 numbers (vector field in 2d or 3d) attached to each
node (N) or element (NEL).

Discontinuous fields are also recognized. In this case, the first
integer has to be NEL, and for each element you must read NDS values
(on the same line) if NDS is the number of nodes per element.


3/ 3d surfaces
--------------

2 different formats are recognized through their extension

* .c3d format: binary files containing structured data:
    x_i, y_j, z_ij, i={1..n}, j={1..m}
(x,y,z) can be either 
  - cartesian coordinates (x,y,z) or
  - cylindrical coordinates (theta, z, r), theta \in {0..2pi}
  - spherical coordinates (theta, phi, r), theta \in {-pi/2..pi/2}
                                         , phi \in {0..2pi}

* .xyz format: ascii file containing unstructured cartesian data:
 x y z (one triplet / line)

* In addition, surfaces given by an equation z=f(x,y) can
be plotted without file. The equation must be written in fortran
synthax, i.e. using the following operators. + - * / ** sin cos etc...

The format c3d is completely described by the program 
src/various/create_c3d.f

c3d files can be translated into ascii files by "clairc3d"
The reverse action (ascii -> binary) is done by "obscurc3d"

Scalar and vector nodal data an be associated to 3d surfaces using
the same file format than for meshes.


