From FLUX

(back to the User Manual or the code section)

Flux.pm (and Flux.xs) contain infrastructure for handling the data interface between the C side libraries and Perl-accessible variables in a generic way. The C libraries are dynamically linked into the current running Perl using a custom symbol table; that is handled by the Flux::Core module. Flux::Core and the ancillary object modules are all loaded automatically when you use Flux.

To load FLUX into a running Perl, you must have PDL installed on your system. Then you say:

use PDL;
use Flux;

and start using FLUX.

The main entry points for constructing and manipulating FLUX simulations are in World.pm, the Flux::World module.

Contents 1 Code Structure 2 Data structure 3 Methods 3.1 r_val 3.2 w_val 3.3 tree 3.4 _rphot / _wphot 3.5 _rnum / _wnum 3.6 _rlong / _wlong 3.7 _rvec / _wvec 3.8 _rvertex 3.9 _rfluxon 3.10 _rconcentration 3.11 _rcoeffs / _wcoeffs 3.12 _rforces/_wforces 3.13 _rbound / _wbound 3.14 _rrecon / _wrecon 3.15 _rdumblist/_wdumblist 3.16 _photosphere 3.17 file_versions 3.18 atan2_oct 3.19 cross_2d 3.20 above_plane 3.21 in_simplex 3.22 interpolate_lin_3d

Code Structure

The Flux module is merely an umbrella for the various object-specific subclasses of Flux::World, Flux::Fluxon, Flux::Vertex, and Flux::Concentration. Almost the only code in it is a generic data access mechanism for tying FLUX objects to Perl hashes.

As with all the FLUX Perl-side modules there is both a pure-Perl module declaration file and a PerlXS interface module. (PerlXS is an interface metalanguage that compiles into glue code. The glue code can be dynamically linked into Perl, and allows snippets of C language to appear as normal predeclared Perl subroutines in the Perl name space).

On the Perl side, the C-language structures are translated to Perl hashes via the tied-hash mechanism: that is, the subclasses of Flux can be treated as Perl hash refs whose keys are mnemonics for structure field names on the C side and whose values are appropriate structured data types on the Perl side. Translation is handled automagically by the interface layer in the Flux module.

Data access on the perl hash side is handled through a kludge: the module declares several package-global Perl variables that translate the Perl-side names of FLUX data fields into numeric codes and access function pointers. The numeric codes are used in Flux.xs to index particular structure fields on the C language side. For more information, see "Structure", below.

Data structure

FLUX objects (and subclasses) are tied hashes that work through the tied hash interface described above. The underlying object that is tied to the hash is a Perl list ref with three elements:

• a pointer to the WORLD (stored as a Perl IV);
• a numeric code indicating what the object type is (these codes are defined in fluxperl.h);
• the label of the object inside the WORLD.

The interface routines use the C side tree_find to locate the object afresh every time that Perl refers to it.

Using the label system simplifies many things having to do with access -- in particular, it prevents stale pointers being left behind in the Perl world because of events that can create or destroy objects in the C library. References to stale objects cause FLUX itself to throw an error, but do not cause core dumps or other bizarreness.

It does make some things more cumbersome -- for example, changing the label field of a FLUX object (e.g. by using the hash interface) maintains the integrity of the C side data structures -- the object gets re-inserted into the tree -- but may cause existing perl variables (that point to that object) to become stale.

Methods

It is not intended that any actual Flux objects be created -- the module is only a container class that provides infrastructure. Only data access methods (and no constructors) are defined here.

Methods with a leading "_" are intended for internal use only, although they are accessible from normal Perl scripts if you insist on using them.

r_val

Usage: $val = $obj->r_val( $struct, $field, $type );

This is the generic field-retriever for the tied hash mechanism. The $struct field is a structure type number (from the global access tables), the $field is a field number (also from the global access tables), and the $type is a magic access-function list ref (also from the global access tables). It springboards into the appropriate access function defined in Flux.xs (and linked to from the access-function list ref), which returns the value to be retrieved. You shouldn't call this yourself under normal circumstances.

w_val

Usage: $obj->w_val( $struct, $field, $type, $val );

This is the generic field-stuffer for the tied hash mechanism. Works just like r_val above, with the same caveats.

tree

Usage: @leaves = $obj->tree( $lname, $whole_tree );

Example: @fluxons = $fluxon->tree( "end_links", 1 );

Uses the tied-hash mechanism to traverse an entire tree with the field name prefix given (for example, the end links structure in a fluxon is tied to the fields "end_links_up", "end_links_left", and "end_links_right"). All the leaves of the tree are returned as a Perl list of appropriate objects (in this case, fluxons). If you set $whole_tree to 1 you get everything including the root; if you set it to 0 (or don't pass it at all) you get just the subtree under the object you passed in.

tree is used for lots of other methods that return whole collections of objects as lists.

_rphot / _wphot

Retrieve/write a photospheric field from the FLUX data structures, returning/accepting it as a Perl hash ref with the magic fields type, origin, and normal. These are in Flux.pm, but just jump into the _photosphere method in Flux.xs.

_rnum / _wnum

(in Flux.xs) - retrieve/write a NUM (floating point) field from the FLUX data structures, returning/accepting it as/from a Perl variable.

_rlong / _wlong

(in Flux.xs) - retrieve/write a long (integer) field from the FLUX data structures, returning/accepting it as/from a Perl variable.

_rvec / _wvec

(in Flux.xs) - retrieve/write a NUM[3] (vector) field from the FLUX data structures, returning/accepting it as/from a 3-PDL variable. The usual PDL permissiveness applies to _wvec, but it will croak if not given either a 1-PDL, a 3-PDL, or something that can be turned into one of those by the PDL constructor.

_rvertex

(in Flux.xs) - retrieve a VERTEX as a Flux::Vertex object.

_rfluxon

(in Flux.xs) - retrieve a FLUXON as a Flux::Fluxon object.

_rconcentration

(in Flux.xs) - retrieve a FLUX_CONCENTRATION as a Flux::Concentration object.

_rcoeffs / _wcoeffs

(in Flux.xs) - retrieve/write a list ref of acceleration coefficients for a World

_rforces/_wforces

(in Flux.xs) - retrieve/write a list ref of force law specifiers (Perl strings); if _wforces gets an invalid one, it will print an error message listing all the valid force law names.

_rbound / _wbound

(in Flux.xs) - retrieve/write a fluxon end condition associated with a flux concentration (translation to/from a Perl string); if _wbound gets an invalid end condition, it will print an error message listing all the valid end condition names.

_rrecon / _wrecon

(in Flux.xs) - retrieve/write a list of reconnection conditions and their parameters (condition is a Perl string; parameters are a list of Perl scalars). If _wrecon gets an invalid reconnection condition, it will print an error message listing valid ones.

_rdumblist/_wdumblist

(in Flux.xs) - retrieve/write all of the values of a DUMBLIST as/from a Perl list ref populated with appropriate objects.

_photosphere

(in Flux.xs) - retrieve/write the state of a WORLD's photosphere as a perl list of 6 elements. This is old-school and is mostly called by _wphot and _rphot.

file_versions

Usage: print Flux::file_versions();

(in Flux.xs) - returns the file version strings in the .c files that were used to construct the current FLUX library in memory.

atan2_oct

Usage: $cheesy_angle = atan2_oct($y, $x);

(in Flux.xs) - provided debugging access to the cheesy approximation to atan used for initial sorting in geometry.c.

cross_2d

Usage: $val = Flux::cross_2d($x1, $x2, $y1, $y2);

(in Flux.xs) - provides debugging access to the cross_2d function in geometry.c. All four input variables must be Perl scalars.

above_plane

Usage: $ok = Flux::above_plane($a,$b,$c, $x);

(in Flux.xs) - given 3-PDLs $a, $b, and $c, which define an oriented plane, determine whether the 3-PDL $x is above or below it. This just jumps out into above_plane() in geometry.c.

in_simplex

Usage: $ok = Flux::in_simplex($a,$b,$c,$d,$x);

(in Flux.xs) - given 3-PDLs describing 5 points, determine whether the 5th one is inside the simplex whose vertices are the other four. This just jumps out into in_simplex() in geometry.c.

interpolate_lin_3d

Usage: $val = Flux::interpolate_lin_3d($x, $simplex, $values)

(in Flux.xs) - test of interpolate_lin_3d in geometry.c. Given a 3-PDL $x, a 3xn-PDL $simplex, and an n-PDL $values, interpolate $values to the location in $x.