User Manual: ASCII data format
From FLUX
(back to the User Manual or the io.c section)
FLUX reads and stores fluxon arenas in a custom ASCII format that is intended to be easily generated, easily parsed, and human readable. It succeeds at the first objective but not so much at the last two. Here is a description of the format.
FLUX input files are considered to manipulate rather than merely to define an arena. Each file is considered to be acting on an existing arena that (at the beginning) is completely empty.
The ASCII file is divided into whitespace-delimited lines that are parsed independently. Each one modifies the state of the simulation. Each line begins with a keywords. The currently accepted keywords are:
- FRAME
- begins the description for a single time step (starts a FRAME block). Currently mostly ignored.
- FINISH
- ends a FRAME block. Can be omitted for the last (or only) FRAME block.
- GLOBAL
- changes the global settings in some way. See the section below.
- NEW
- creates a new FLUX_CONCENTRATION - an endpoint for fluxons.
- LINE
- creates a new FLUXON connecting two FLUX_CONCENTRATIONs.
- VERTEX
- creates a new VERTEX at a specified location on a particular FLUXON.
- VNEIGHBOR
- creates a neighbor relation between two vertices
The lines are parsed in order to build up the geometry of the simulation. The exact format of each type of keyword line is listed below.
Contents |
Keyword formats
FRAME/FINISH
FRAME n
Starts a description of the simulation boundary for a particular time step. This is currently not used -- it is intended to be useful for future files that include a full description of a time-deendent boundary. You should start most files with the line "FRAME 1".
FINISH
Ends a frame description. Parsing of the file stops at the FINISH. Can be omitted if you aren't storing time dependent data (which you aren't, yet).
GLOBAL
GLOBAL sets up global parameters of the simulation, including boundary conditions, force laws, and even step scaling laws. Here're formats for different styles of GLOBAL statement:
GLOBAL FORCE
GLOBAL FORCE name1 name2 ...
Sets up the force laws that are to be used for this simulation. The names must be names of force laws that are compiled into the code (they're stored in a global array defined in physics.c). For simple NLFFF relaxations you probably want f_pressure_equi2, f_curvature, and f_vertex.
GLOBAL PHOTOSPHERE
GLOBAL BOUNDARY x1 x2 x3 n1 n2 n3 type
Declares high-beta line-tied boundary at the specified location, with the specified type. Note that nothing prevents you from placing naked flux concentrations anywhere in space -- the boundary merely has the property of being impenetrable to fluxons. The x and n vectors are parameters used to specify the surface. The type is as follows:
- 0 - no boundary
- x and n are ignored.
- 1 (or 'PLANE') - planar boundary
- x is the origin vector; n is a normal vector.
- 2 (or 'SPHERE') - spherical boundary
- x is the center of the sphere; n1 is its radius. n3 is ignored. If n2 is zero or positive, the system is outside the sphere. If n2 is negative, the system is inside the sphere.
- 3 (or 'CYL') - cylindrical boundary
- x is the center of the cylinder; The length of n is its radius. The cylinder's axis is in the direction of n.
GLOBAL OPEN
GLOBAL OPEN x1 x2 x3 r auto
Sets the source surface for a spherical open boundary condition: fluxons with OPEN endpoints are forced to end on the surface of a sphere centered at x, with radius r. The auto flag should be 1 for automatic opening (by cut) of fluxons that cross the open boundary, or 0 for no automatic opening.
GLOBAL COEFFS
GLOBAL COEFFS n c1 ... cn
This sets the weighting coefficients for accelerating low-spatial-frequency eigenmodes. See User Manual: relaxation for a description of how this works.
GLOBAL REL_STEP
GLOBAL REL_STEP step
Sets the current relaxation step number field in the arena. This is used for bookkeeping but doesn't affect the simulation directly.
GLOBAL DTAU
GLOBAL DTAU dτ
Sets the τ relaxation timestep in the simulation. As τ is measured in local linear relaxation times, you generally want it to be less than 1, for stability. See User Manual: relaxation for a full description.
GLOBAL SCALING
GLOBAL SCALING param val
Sets the power law used for each of several local parameters that scale the relaxation step. This affects relaxation speed and stability. The param can be one of:
- B (local magnetic field)
- D (distance to the nearest fluxel)
- DS (difference in force between this fluxel and its neighbors)
- S (stiffness coefficient)
See User Manual: relaxation for a full description.
GLOBAL STATE
GLOBAL STATE n
Sets the bookkeeping simulation-state flag to the given value. Doesn't affect the simulation directly. Not currently useful.
GLOBAL SKEWFLAG
GLOBAL SKEWFLAG s
Turns on or off a particular experimental geometric hack in the non-Euclidean projection function for neighbor calculation. Should be off.
NEW
NEW label x1 x2 x3 flux
Creates a new flux concentration with the given label (label should be an integer), located at x, with the given amount of magnetic flux (positive or negative). If a flux concentration already exists with that label, then it moves the old one to the new location. The flux parameter is stored in the FLUX_CONCENTRATION structure, but has no direct effect on the simulation -- it is intended for bookkeeping the values of the fluxons that come into and/or out of the flux concentration. By convention, positive flux concentrations are sources that should serve as fluxon beginnings, and negative ones are sinks that should serve as fluxon ends -- but the code does not enforce that directionality.
The first 99 negative flux concentration labels are reserved (-1 through -99) and should not be used!
LINE
LINE label fc1 fc2 flux
LINE label start_label end_label fc1 fc2 flux
Creates a fluxon with the given label (label should be an integer), starting at the flux concentration labeled fc1 and ending at the flux concentration labeled fc2. The first few negative flux concentration labels are special and are used for open and plasmoid fluxons. To make a fluxon that is open at the beginning, fc1 should be -1. To make a fluxon that is open at the end, fc2 should be -2. To make a fluxon that is a plasmoid, fc1 should be -3 and fc2 should be -4.
The second form of the LINE command specifies the serial number of placeholder vertices that are put at the ends of the fluxon automatically. If you specify the start_label and end_label, the vertices will still be created automatically -- they will just be assigned the labels you give, rather than having new unique labels assigned to them.
VERTEX
VERTEX fluxon label pos x1 x2 x3
Creates a new vertex on the given fluxon, with unique label label (should be an integer), at position pos counting from the start of the fluxon. The start and end points of the fluxon are defined implicitly and don't need to be declared. The first nontrivial vertex is at position 1.
VNEIGHBOR
VNEIGHBOR v1 v2
VN v1 v2
Maked vertex v2 a neighbor of v1. This is useful because neighbor calculation is much more expensive working from scratch than from a previous time step. The initial neighbor calculation runs in O(n2) time and can take many seconds or minutes for not-very-large simulations. Subsequent time steps run in O(n) time. By storing the existing neighbor relations with VNEIGHBOR, the code avoids having to do another global search when a file is read in. You can abbreviate VNEIGHBOR with just VN.
Example
Here is an annotated definition file, generated with the Perl method Flux::World::string().
The top of the definition file consists of global definitions that apply to the whole world. The FRAME statement is currently ignored but may be used for storage of time-dependent evolution later.
The COEFFICIENTS tag sets the final step for each vertex to be dependent on only calculated step for that vertex, and not on any of its neighbors' motions. An impermeable planar boundary is set to pass through the origin, with a normal vector of (0,0,1).
FRAME 0 GLOBAL FORCES f_pressure_equi2b f_curvature f_vertex4 GLOBAL STATE 0 (NEW) GLOBAL BOUNDARY PLANE 0 0 0 0 0 1 GLOBAL SCALING B 0 GLOBAL SCALING D 2 GLOBAL SCALING S 0 GLOBAL SCALING DS 0 GLOBAL RSTEP 0 GLOBAL DTAU 0.100000 GLOBAL COEFFICIENTS 1 1.000000 GLOBAL SKEW_HANDLING 0
This file has four fluxons, hence eight endpoints. It happens to have one fluxon per flux concentration, so that eight flux concentrations are needed. Flux concentrations 101 and 102 correspond to a single fluxon (source and sink, respectively), etc.
NEW 101 -0.475 -0.025 0 1 NEW 102 0.525 0.025 1.39e-06 -1 NEW 103 -0.475 0.025 0 1 NEW 104 0.525 -0.025 1.39e-06 -1 NEW 105 -0.525 -0.025 0 1 NEW 106 0.475 0.025 1.26e-06 -1 NEW 107 -0.525 0.025 0 1 NEW 108 0.475 -0.025 1.26e-06 -1
Comment lines in the file begin with '#'. Here, fluxon definitions are grouped by source flux concentration. There are no plasmoids (FC -3) and no fluxons originating from an open boundary (FC -1), so those sections are blank. Each source flux concentration is noted in a comment and followed by all the fluxons that originate from that flux concentration.
There are two forms of the LINE command. In the six-number form shown here, the "-2002" and "-2001" refer to placeholder vertices that are automatically generated for each fluxon. When creating a new FLUX arena, you needn't worry about these placeholder vertices, which will be assigned their own unique numbers automatically; omitting the placeholder vertices gives the simpler four-number form of the LINE command.
# FC -3
# FC -1
# FC 101
LINE 1001 -2002 -2001 101 102 1
VERTEX 1001 1002 1 -0.449 -0.0327 0.186
VERTEX 1001 1003 2 -0.354 -0.0354 0.354
VERTEX 1001 1004 3 -0.197 -0.0327 0.474
VERTEX 1001 1005 4 -6.97e-07 -0.025 0.525
VERTEX 1001 1006 5 0.204 -0.0135 0.492
VERTEX 1001 1007 6 0.379 2.71e-13 0.379
VERTEX 1001 1008 7 0.492 0.0135 0.204
The fluxon definition line is followed by all of its vertices and their locations, in order. It would be marginally faster to load the file by listing all the vertices in reverse order and listing their position as "1" (instead of the current listing in numerical order), but the forward listing is more readable.
# FC 103
LINE 1009 -2018 -2017 103 104 1
VERTEX 1009 1010 1 -0.432 0.0135 0.179
VERTEX 1009 1011 2 -0.329 -9.02e-14 0.329
VERTEX 1009 1012 3 -0.179 -0.0135 0.432
VERTEX 1009 1013 4 -6.3e-07 -0.025 0.475
VERTEX 1009 1014 5 0.186 -0.0327 0.449
VERTEX 1009 1015 6 0.354 -0.0354 0.354
VERTEX 1009 1016 7 0.474 -0.0327 0.197
# FC 105
LINE 1017 -2034 -2033 105 106 1
VERTEX 1017 1018 1 -0.492 -0.0135 0.204
VERTEX 1017 1019 2 -0.379 9.02e-14 0.379
VERTEX 1017 1020 3 -0.204 0.0135 0.492
VERTEX 1017 1021 4 -6.97e-07 0.025 0.525
VERTEX 1017 1022 5 0.197 0.0327 0.474
VERTEX 1017 1023 6 0.354 0.0354 0.354
VERTEX 1017 1024 7 0.449 0.0327 0.186
# FC 107
LINE 1025 -2050 -2049 107 108 1
VERTEX 1025 1026 1 -0.474 0.0327 0.197
VERTEX 1025 1027 2 -0.354 0.0354 0.354
VERTEX 1025 1028 3 -0.186 0.0327 0.449
VERTEX 1025 1029 4 -6.3e-07 0.025 0.475
VERTEX 1025 1030 5 0.179 0.0135 0.432
VERTEX 1025 1031 6 0.329 -2.71e-13 0.329
VERTEX 1025 1032 7 0.432 -0.0135 0.179
After all the fluxons and vertices are declared, any neighbor relations follow. A freshly declared arena has no neighbor relations stored, and must be initialized with a global neighbor update (on the Perl side, update_neighbors(1)). Once the neighbor relations have been seeded, a much faster local neighbor update (update_neighbors(0)) can be used.
VNEIGHBOR -2050 1018 VNEIGHBOR -2050 -2034 VNEIGHBOR -2050 1010 VNEIGHBOR -2050 -2018 VNEIGHBOR -2050 1024 VNEIGHBOR -2034 1002 VNEIGHBOR -2034 -2002 VNEIGHBOR -2034 1026 VNEIGHBOR -2034 -2050 VNEIGHBOR -2018 -2050 VNEIGHBOR -2018 1002 VNEIGHBOR -2018 -2002 VNEIGHBOR -2018 1032 VNEIGHBOR -2018 1024 VNEIGHBOR -2018 1026 VNEIGHBOR -2002 -2034 VNEIGHBOR -2002 1016 VNEIGHBOR -2002 1015 VNEIGHBOR -2002 1032 VNEIGHBOR -2002 1011 VNEIGHBOR -2002 1010 VNEIGHBOR -2002 -2018 VNEIGHBOR -2002 1018 VNEIGHBOR 1002 1 VNEIGHBOR 1002 1015 VNEIGHBOR 1002 1032 VNEIGHBOR 1002 1012 VNEIGHBOR 1002 1011 VNEIGHBOR 1002 1010 VNEIGHBOR 1002 -2018 VNEIGHBOR 1002 1019 VNEIGHBOR 1002 1018 VNEIGHBOR 1002 -2034 VNEIGHBOR 1003 1015 VNEIGHBOR 1003 1014 VNEIGHBOR 1003 1013 VNEIGHBOR 1003 1012 VNEIGHBOR 1003 1011 VNEIGHBOR 1003 1010 VNEIGHBOR 1003 1020 VNEIGHBOR 1003 1019 VNEIGHBOR 1003 1018 VNEIGHBOR 1004 1014 VNEIGHBOR 1004 1013 VNEIGHBOR 1004 1012 VNEIGHBOR 1004 1011 VNEIGHBOR 1004 1021 VNEIGHBOR 1004 1020 VNEIGHBOR 1004 1019 VNEIGHBOR 1005 1014 VNEIGHBOR 1005 1013 VNEIGHBOR 1005 1012 VNEIGHBOR 1005 1022 VNEIGHBOR 1005 1021 VNEIGHBOR 1005 1020 VNEIGHBOR 1006 1015 VNEIGHBOR 1006 1014 VNEIGHBOR 1006 1013 VNEIGHBOR 1006 1023 VNEIGHBOR 1006 1022 VNEIGHBOR 1006 1021 VNEIGHBOR 1007 1016 VNEIGHBOR 1007 1015 VNEIGHBOR 1007 1014 VNEIGHBOR 1007 1024 VNEIGHBOR 1007 1023 VNEIGHBOR 1007 1022 VNEIGHBOR 1008 1016 VNEIGHBOR 1008 1015 VNEIGHBOR 1008 1024 VNEIGHBOR 1008 1023 VNEIGHBOR 1010 1003 VNEIGHBOR 1010 1002 VNEIGHBOR 1010 -2002 VNEIGHBOR 1010 1032 VNEIGHBOR 1010 1024 VNEIGHBOR 1010 1027 VNEIGHBOR 1010 1026 VNEIGHBOR 1011 1003 VNEIGHBOR 1011 1002 VNEIGHBOR 1011 1 VNEIGHBOR 1011 1032 VNEIGHBOR 1011 1028 VNEIGHBOR 1011 1027 VNEIGHBOR 1011 1026 VNEIGHBOR 1012 1004 VNEIGHBOR 1012 1003 VNEIGHBOR 1012 1 VNEIGHBOR 1012 1030 VNEIGHBOR 1012 1029 VNEIGHBOR 1012 1028 VNEIGHBOR 1012 1027 VNEIGHBOR 1013 1004 VNEIGHBOR 1013 1002 VNEIGHBOR 1013 -2002 VNEIGHBOR 1013 1 VNEIGHBOR 1013 1031 VNEIGHBOR 1013 1030 VNEIGHBOR 1013 1029 VNEIGHBOR 1013 1028 VNEIGHBOR 1013 1005 VNEIGHBOR 1014 1003 VNEIGHBOR 1014 1002 VNEIGHBOR 1014 -2002 VNEIGHBOR 1014 1 VNEIGHBOR 1014 1032 VNEIGHBOR 1014 1031 VNEIGHBOR 1014 1030 VNEIGHBOR 1014 1029 VNEIGHBOR 1014 1007 VNEIGHBOR 1014 1006 VNEIGHBOR 1014 1005 VNEIGHBOR 1015 1 VNEIGHBOR 1015 1032 VNEIGHBOR 1015 1031 VNEIGHBOR 1015 1030 VNEIGHBOR 1015 1008 VNEIGHBOR 1015 1007 VNEIGHBOR 1015 1006 VNEIGHBOR 1016 -2002 VNEIGHBOR 1016 1032 VNEIGHBOR 1016 1031 VNEIGHBOR 1016 1008 VNEIGHBOR 1016 1007 VNEIGHBOR 1018 1003 VNEIGHBOR 1018 1002 VNEIGHBOR 1018 -2002 VNEIGHBOR 1018 1027 VNEIGHBOR 1018 1026 VNEIGHBOR 1018 -2050 VNEIGHBOR 1019 1004 VNEIGHBOR 1019 1003 VNEIGHBOR 1019 1002 VNEIGHBOR 1019 1028 VNEIGHBOR 1019 1027 VNEIGHBOR 1019 1026 VNEIGHBOR 1020 1005 VNEIGHBOR 1020 1004 VNEIGHBOR 1020 1003 VNEIGHBOR 1020 1029 VNEIGHBOR 1020 1028 VNEIGHBOR 1020 1027 VNEIGHBOR 1021 1006 VNEIGHBOR 1021 1005 VNEIGHBOR 1021 1004 VNEIGHBOR 1021 1030 VNEIGHBOR 1021 1029 VNEIGHBOR 1021 1028 VNEIGHBOR 1021 1027 VNEIGHBOR 1022 1007 VNEIGHBOR 1022 1006 VNEIGHBOR 1022 1005 VNEIGHBOR 1022 1031 VNEIGHBOR 1022 1030 VNEIGHBOR 1022 1029 VNEIGHBOR 1022 1028 VNEIGHBOR 1022 1027 VNEIGHBOR 1022 1026 VNEIGHBOR 1023 1008 VNEIGHBOR 1023 1007 VNEIGHBOR 1023 1006 VNEIGHBOR 1023 1032 VNEIGHBOR 1023 1031 VNEIGHBOR 1023 1030 VNEIGHBOR 1023 1029 VNEIGHBOR 1023 -2018 VNEIGHBOR 1023 1026 VNEIGHBOR 1023 1 VNEIGHBOR 1024 1007 VNEIGHBOR 1024 1032 VNEIGHBOR 1024 1031 VNEIGHBOR 1024 1030 VNEIGHBOR 1024 -2018 VNEIGHBOR 1024 1026 VNEIGHBOR 1024 -2050 VNEIGHBOR 1024 1008 VNEIGHBOR 1026 1019 VNEIGHBOR 1026 1018 VNEIGHBOR 1026 -2034 VNEIGHBOR 1026 1011 VNEIGHBOR 1026 1010 VNEIGHBOR 1026 -2018 VNEIGHBOR 1026 1 VNEIGHBOR 1027 1020 VNEIGHBOR 1027 1019 VNEIGHBOR 1027 1018 VNEIGHBOR 1027 1012 VNEIGHBOR 1027 1011 VNEIGHBOR 1027 1010 VNEIGHBOR 1027 -2018 VNEIGHBOR 1027 1 VNEIGHBOR 1027 1024 VNEIGHBOR 1027 1023 VNEIGHBOR 1027 1022 VNEIGHBOR 1028 1020 VNEIGHBOR 1028 1013 VNEIGHBOR 1028 1012 VNEIGHBOR 1028 1011 VNEIGHBOR 1028 1010 VNEIGHBOR 1028 1 VNEIGHBOR 1028 1024 VNEIGHBOR 1028 1023 VNEIGHBOR 1028 1021 VNEIGHBOR 1029 1014 VNEIGHBOR 1029 1013 VNEIGHBOR 1029 1012 VNEIGHBOR 1029 1011 VNEIGHBOR 1029 1 VNEIGHBOR 1029 1022 VNEIGHBOR 1029 1021 VNEIGHBOR 1030 1015 VNEIGHBOR 1030 1014 VNEIGHBOR 1030 1013 VNEIGHBOR 1030 -2018 VNEIGHBOR 1030 1 VNEIGHBOR 1030 1023 VNEIGHBOR 1030 1022 VNEIGHBOR 1031 1015 VNEIGHBOR 1031 1014 VNEIGHBOR 1031 -2002 VNEIGHBOR 1031 -2018 VNEIGHBOR 1031 1024 VNEIGHBOR 1031 1023 VNEIGHBOR 1031 1022 VNEIGHBOR 1032 1015 VNEIGHBOR 1032 -2002 VNEIGHBOR 1032 -2018 VNEIGHBOR 1032 1024 VNEIGHBOR 1032 1023 VNEIGHBOR 1032 1016
