From FLUX

(Back to the user manual or the code section)

Autoload routines are automatically compiled by the PDL autoload module (PDL::AutoLoader) when needed. They are provided in the distribution tree, in the directory .../pdl/PDL/, and are defined in files with the form name.pdl.

Contents 1 World Construction & Fluxon Placement 1.1 twisted_loop 1.2 place_loop_vertex 1.3 fluxon_placement_fs 1.4 fluxon_placement_hilbert 1.5 make_world 1.6 random_carpet 1.7 coronal_hole 2 Rendering 2.1 random_colors 3 Control 3.1 simple_relaxer 4 Evolution 4.1 interp_duction 4.2 rotate_poles 4.3 rotate_poles_arcade 4.4 rotate_starts 5 Testing 5.1 neighbor_check 5.2 test_freeze 5.3 test_hull 5.4 test_ls_dist 5.5 test_p_ls_dist 5.6 test_proj 5.7 test_projmatrix

World Construction & Fluxon Placement

World construction options are a bit limited: originally, the only way to construct a new world was with Flux::World::read_world or Flux::World::str2world, so the high level construction routines still generate snippets of string that can be concatenated to make a world description file.

The twisted_loop routine is a basic building block of a priori simulations -- it creates an elliptical loop of rectangular cross section and a specified number of uniform twists along its length.

To shoot field lines through an existing analytic field or datacube, you'll need to use your own rk4 shooter. One is available in the sswpdl distribution that is part of SolarSoft. A more sophisticated shooter will be included in a future release. Finding field line starting points from a magnetogram is the dithering problem and it is handled by fluxon_placement_fs and fluxon_placement_hilbert.

If you develop a fluxon geometry as a collection of 3xN PDLs, make_world will convert it to a line-tied Flux::World.

Some yet higher level constructors can be used for specific test cases: place_loop_vertex, random_carpet, and coronal_hole are useful for testing, but also as demos of how to use the other construction tools.

twisted_loop

$s = twisted_loop($from, $to, $steps, $nm, $spacing, $twist, $fclab, $flab, $v1)

twisted_loop generates a fragmentary ASCII World file that contains a single coherent, possibly twisted, bundle of fluxons. It can be used to hand-assemble test cases.

Arguments are:

$from

This is 3-PDL containing the coordinates of the center of the source flux concentration.

$to

This is a 3-PDL containing the coordinates of the center of the sink flux concentration.

$steps

This is the number of fluxels along each fluxon.

$nm

This is a 2-PDL containing the (transverse, radial) count of fluxons in the bundle. The 0 coordinate gives the count of fluxons perpendicular to the source-sink line. The total count of fluxons is $nm->(0) * $nm->(1).

$spacing

This is the distance between adjacent fluxons at the source or sink.

$twist

This is the entrained twist in the bundle, in turns. The whole bundle is twisted coherently around its centerline, by this amount.

$fclab

This is the initial flux concentration label to use. You are responsible for making sure that it and enough following numbers are unused in your existing model, if any.

$flab

This is the initial fluxon & vertex label to use. You are responsible for making sure there are no collisions.

$v1

This is an initial guide vector. The default is (0,0,1). The guide vector is used to set the vertical scale and direction of the loop's arch. You can use it to guide the path of the arch, in case you need to avoid obstacles or shoot it in an odd direction.

place_loop_vertex

This is a helper routine for twisted_loop, above.

fluxon_placement_fs

Dithers fluxon endpoints onto a magnetogram. Deprecated for most uses. See User Manual: Code: Misc: fluxon_placement_fs.

fluxon_placement_hilbert

Dithers fluxon endpoints onto a magnetogram. See User Manual: Code: Misc: fluxon_placement_hilbert.

make_world

$w = make_world( $opt, @geom ) $w = make_world( @geom )

This is a very simple geometry-to-world converter. You place all the vertices you want in a list of (3xn) PDLs, one PDL per fluxon, and make_world generates a Flux::World with default characteristics and the specified geometry. All the endpoints are line-tied, so if you want plasmoids or open fluxons you must edit the world post-facto.

random_carpet

$world = random_carpet($num, $n, $a)

Generates a nonphysical, randomly connected magnetic carpet of discrete flux tubes. This was used to test scaling properties for the initial paper. It's still in the distribution mostly because it can serve as a demo for a priori autogenerated fluxon fields.

coronal_hole

$world = coronal_hole()

This is the full-Sun sim generator that was used for early spherical geometry tests. It's left in the distribution primarily as a demo of how to autogenerate a simple, "realistic" Sun in spherical geometry.

Rendering

Most of the rendering work is accomplished within the Flux::World object, by Flux::World::render. Helper routines are sometimes needed. The only one so far is "random_colors".

random_colors

$frgb = random_colors($world, \%opt);

$world->render(1,{rgb_fluxons=>$frgb});

random_colors generates a lookup table of slightly different (r,g,b) values for each fluxon in a simulation. The slightly differnet values help the eye follow individual fluxons rather than simply seeing them as a mass of color.

It's used to produce a randomly generated but persistent color map to guide the eye. The return value is a hash ref, each key of which is a fluxon ID and each element of which is a 3-PDL with an rgb value. The hash ref is suitable for feeding to Flux::World::render.

Some options are available to help you fine-tune the color choices. You can specify a particular range in HSV' coordiates (hue, relative saturation, brightness). Each coordinate ranges from 0 to 1. You can specify them in the options hash. Valid options are:

hr

"Hue range": a list ref containing two values, a minimum and maximum. Hue is interpreted as normalized angle around the color wheel. The primary colors are at 0 (blue), 0.33 (red), and 0.67 (green). If you want a range around one of the primary or secondary colors you can give it as a name rather than a range: "red", "blue", "green", "yellow", "magenta", or "cyan".

sr

"Saturation range": This is relative saturation (relative to the luminance, below) -- the RGB gamut is a cube in color space, and hence the constant-luminance cross section is a triangle or hexagon. Hence, specifying a very bright luminance will give you pastels rather than extremely bright saturated colors. For highest saturation, choose a luminance range near 50%. Like hr, it is a 2-list containing the (minimum, maximum) values, in the range [0,1].

vr

"Luminance range": Ranges from 0 (black) to 1 (white). Like the others, it is a 2-list containing the (minimum, maximum) values, in the range [0,1].

Control

At the moment, there's really only one high-level relaxation control routine, simple_relaxer. It handles, er, simple relaxation loops, calling the appropriate entry points to advance a relaxation. More control routines will follow in future releases, but for now you must roll your own relaxation loop around simple_relaxer if you want more sophisticated behavior than it can give.

simple_relaxer

simple_relaxer($world, $int_flag, $gl_flag, $steps, $opt)

simple_relaxer is the basic relaxation outer loop. it began as a quick-and-dirty demo but has grown to be reasonably full featured.

The $world is a Flux::World object.

The $int_flag and $gl_flag are flags indicating, respectively, whether the relaxation is to be "interactive" (pausing after each render for the user to manipulate the POV) and whether to do global neighbor searches at each relaxation step (very slow compared to the normal differential neighbor search); both of those flags should be set to 0 for normal operation).

$steps is the number of relaxation steps to take. The step size is determined by $world->{dtau} and the current relaxation step is tracked in $world->{rel_step}.

$options is a hash ref that adjusts the behavior. Useful options are:

movie_n

If set, this will render and save to disk an image of the

simulation every n frames. The disk files will be formed from the movie_f template, below. The frames are rendered to the screen with the Flux::World::render method, then screen-captured and saved to disk.

movie_f

If you generate frames for a relaxation movie, you can set their filename template with this string -- it is interpreted as the control string for sprintf, with a single following argument - the relaxation step number. The default string is "flux-movie-%4.4d.png". You can use the dot-suffix to set the file type; most standard image formats are supported.

disp_n

If set, this will render an image to the screen every n frames. The default value is 10. If you set it to 0, then no images will be rendered at all.

render_opt

If set, this is itself a hash ref containing options to send to the Flux::World::render method when rendering to the screen.

range

If set, this should be a 3x2-PDL containing opposite corners of the spatial cube to render. It is passed directly to Flux::World::render.

auto

If set, dtau is adjusted automatically. This is deprecated.

The recommended force laws and tau settings may be found elsewhere.

simple_relaxer has no provision (at the moment) for grid refinement; for this reason, you may want to include an outer loop around your call(s) to simple_relaxer, to call fix_curvature, save world snapshots, and/or check a relaxaton condition other than simple relaxation step count.

Evolution

Evolution of the field between time steps is accomplished by moving any line-tied boundaries and re-relaxing. The motion must, however, be smooth: simply translating the last vertex of each fluxon could easily cause intersections and other difficulties. FLUX comes with some utilities to smoothly distort the field near the line-tied boundary, before relaxing to find the new force-free state.

The smooth distortions are accomplished by specifying motion at a few specific points, and then interpolating those motions for every vertex in the simulation. The tie-points are referred to as "ductions" and require six numbers in a 3x2 PDL. The (:,(0)) vector is the initial location of the duction and (:,(1)) vector is the displacement at that location. The main subroutine, interp_duction, accepts a 3x2xn PDL describing n ductions, and uses inverse-square weighting to interpolate the motions to the entire field of a Flux::World.

interp_duction

$new_locations = interp_duction($ducts, $locations)

Interp_duction interpolates the motion specified in a collection of ductions (stored as a 3x2xn PDL), onto a set of locations (stored as a 3xm PDL). The motion at each location is the weighted average of all the duction motions, weighted by 1/r^2 between the subject point and the corresponding duction tiepoint.

This is the basic routine that is used for distorting fluxon fields between time steps: the smooth interpolation between tie points makes it unlikely that any fluxons will cross one another, for reasonably small motions (ie not much larger than the distance between flux concentrations on the simulation boundary).

rotate_poles

rotate_poles($world, $center_north, $angle_north, $center_south, $angle_south)

This is a simple demonstration routine that rotates all of the north and south magnetic poles in a simulation about two common centers, by two common angles (one of each for all the north poles, and one of each for all the south poles). It's useful mainly for toy models, e.g. winding a simple flux rope, but is left in the distribution as a useful demo. The rotations are implemented by direct analytical calculation of the motion of each flux concentration. They are then formed into a 3x2xn duction PDL, which is suitable for feeding to interp_duction to find a smooth distortion of the entire spatial field of the world.

rotate_poles_arcade

rotate_poles_arcade($world, $center_north, $angle_north, $center_south, $angle_south, $thresh)

This is a modified version of rotate_poles that was used by Rachmeler to generate her models of winding flux tubes under a static arcade. The only difference is that fluxons with a label greater than or equal to $thresh are ignored -- so if you have a static arcade with numerically high labels, it is not rotated.

rotate_starts

rotate_starts($world, $center, $angle)

Similar to rotate_poles, above, but only rotates north poles.

Testing

Several test scripts survive from initial development of FLUX. They are kept as useful demonstrations of library access and for occaional regression testing as code development continues.

neighbor_check

$not_ok = neighbor_check($world)

Walks through a Flux::World and checks the neighbor relations for consistency. Every neighbor list should be duplicate-free. Every entry in a vertex's neighbor list should have the original vertex in its nearby list, and vice versa. Prints an error message and returns a flag if the world is inconsistent.

test_freeze

test_freeze()

This isn't actually a subroutine definition, but a script -- the file gets executed by the autoloader, but fails to define any subroutines at all. It relaxes an extremely simple fluxon system (the 'simple-8' in the menagerie) to exercise all the basic elements of the Flux library.

test_hull

test_hull()

This is actually a script - invoking the routine will cause the autoloader to run the script, but no subroutine is actually defined. It loads a simple fluxon system and plots the 2-D hull for each vertex in it.

test_ls_dist

test_ls_dist()

This is actually a script - invoking it will cause the autoloader to run the script, but does not declare the subroutine. This generates a suite of line segments and plots the distance between them as one rotates relative to the other.

test_p_ls_dist

test_p_ls_dist()

This is actually a script: invoking the name causes the autoloader to run the script, but it does not declare a subroutine. Exercises the point -- line-segment distance calculator by generating a series of line segments and relative locations of a nearby point, and plotting the distance between them.

test_proj

test_proj()

This is actually a script - invoking the name causes the autoloader to run the script, but does not declare the subroutine. (A helper subroutine, _test_proj_, gets declared). Tests some standard cases for the projection matrix generator (which generates a rotation matrix to move a specified vector to the Z axis).

test_projmatrix

test_projmatrix()

This is actually a script: invoking the name causes the autoloader to execute the script, but does not declare the subroutine. Generates a large suite of vectors and uses the projmatrix routine to rotate each one to the Z axis.