fluxon-mhd: A FLUX repository from lowderchris

This is FLUX, the Field Line Universal Relaxer

For full documentation visit the FLUX wiki:
https://github.com/lowderchris/fluxon-mhd/wiki

FLUX is a prototype MHD solver that is currently able to find nonlinear force-free fields with an exactly specified topology in a quasi-static, infinitely conductive, low-beta medium. Unlike conventional extrapolation codes, FLUX accepts as input a collection of field line shapes that do not necessarily have physical meaning but that do have the correct topology that you want to study.

The FLUX engine relaxes the position of those field lines until they approximate the physical force-free state with the same topology that you specified.

FLUX consists of two parts: a relaxation engine, written in C, and a control interface in Perl. The control interface is intended to be used with Perl Data Language (PDL). If you do not have PDL on your system, you can get it for free from http://pdl.perl.org. PDL compiles "out of the box" on most UNIX systems, and a "native" version exists for Microsoft Windows.

The authors gratefully acknowledge support from NASA's Living With A Star and Solar/Heliospheric Physics programs, and from the Southwest Research Institute.

All source files are copyright (C) 2004-2023 by the authors unless otherwise marked. You may modify and/or make copies of this software under the terms of the Gnu Public License, version 2 (GPL v2). You should have received a copy of the GPL v2 with this software; it is present in the file "COPYING". If you do not have a copy you may obtain one online from "http://www.gnu.org/licenses/gpl-2.0.html" or by writing to the Free Software Foundation, 59 Temple Place, Suite 330, Boston, MA 0211-1307 USA.

THIS SOFTWARE COMES WITH NO WARRANTY OF ANY KIND.

Authors:
Craig DeForest (SwRI)
Charles Kankelborg (MSU)
Derek Lamb (SwRI)
Chris Lowder (SwRI)
Chris Gilly (SwRI)
Laurel Rachmeler (then at CU Boulder & SwRI)
Alisdair Davey (then at SwRI)

Contributors (gratefully acknowledged):
Nathan Schwadron
Teddy Walls
Christopher Plumberg

--------
INSTALLATION INSTRUCTIONS

There are two components to FLUX: a C simulation library (libflux.a) and a Perl module (Flux.pm, etc). Automake and Perl's ExtUtils::MakeMaker don't play nicely together, and libflux.a needs to be installed before the Perl module is built. Therefore, we build and install the C and Perl components separately.

You should declare up to two environment variables, which are only needed for build and installation:

FL_PREFIX (required, defaults to /usr/local):
Where the FLUX simulation library and include files should be installed.

PL_PREFIX (optional, no default):
Where the Perl front-end module should be installed. This location should be in Perl's @INC list. Try doing ' perl -e "print join(qq|\n|,@INC,q||);" ' at the command line to see the contents of this list. If $PL_PREFIX/lib/perl5 is not included in @INC, then Perl will not be able to find the Flux module after installation. You can add $PL_PREFIX/lib/perl5 to your PERL5LIB environment variable to solve that problem. Or you can just leave PL_PREFIX undefined and Perl will do the Right Thing.

After installation, some autoloading routines will be installed for you. See the docs for PDL::AutoLoader (https://metacpan.org/pod/PDL::AutoLoader) for a description of this handy feature of PDL. Instructions come at the end of the installation script.

0) The zeroth line exports the environment variables you have already declared.
1) The first line builds the simulation library. A copy of the library and include files will be installed into a directory named 'sandbox', so if you use that for the $FL_PREFIX, then nothing will be installed system wide. This may be good for testing.
2) The second line installs libflux.a and some header files into $FL_PREFIX/lib and $FL_PREFIX/include/flux, respectively.
3) The third line builds the Perl module (and prepares it to install in the location given by $PL_PREFIX).
4) The fourth line runs the test suite.
5) The fifth line installs Flux.pm, etc.
6) The sixth line is optional, and cleans up the local environment if desired (or you may just exit the shell).

Note the 'sudo' on lines 2 and [if required based on PL_PREFIX] 4

$ export FL_PREFIX PL_PREFIX
$ make libbuild
$ sudo make libinstall
$ make pdlbuild
$ make pdltest
$ [sudo] make pdlinstall
$ export -n FL_PREFIX PL_PREFIX

IFF both the library and the module are going to be installed in root-owned or user-owned locations, you can shortcut the above with

$ export PL_PREFIX FL_PREFIX
$ [sudo] make everything
$ export -n FL_PREFIX PL_PREFIX

for example, to install everything into your home directory /home/user/local/lib, /home/user/local/include, etc., you could do (making sure to substitute the user home directory path, without tildes):

$ export PL_PREFIX='/home/user/local'
$ export FL_PREFIX='/home/user/local'
$ make everything

--------

This is the FLUX top-level directory.

Subdirectories include:
lib -- the central libflux.a core simulation library
(this gets installed into $FL_PREFIX/lib/)

doc -- some docs (deprecated; see https://github.com/d-lamb/fluxon-mhd/wiki
for more up-to-date information.)

include -- 'c' header files
(these get installed into $FL_PREFIX/include/flux/)

pdl -- PDL glue code and perl modules

pdl/PDL -- PDL autoload subroutines

py -- Python visualization and analysis tools

--------

RELEASE NOTES FOR v2.3 (26-May-2023):
- Updated for compatibility with newer versions of PDL
- Organization of solar wind processing codes
- Development of automated processing module
- Other consolidated changes and closing of branches

RELEASE NOTES FOR v2.2 (22-Nov-2008):
- Mass is actively tracked in the data structures
- Binary save files are supported; all files are auto-gzipped if they have a '.gz' extension
- First-stage parallelization appears functional -- the code can spawn to make use of multiple CPU cores on the local machine.
- Interpolation of all scientific values onto arbitrary locations is now possible.
- New reconnection criteria make reconnection "in the wrong direction" much less common.
- Multiple bug fixes in the perl interface code
- Data structure labels can now be edited via the perl hash interface.
- There is better support for motion and interaction of flux concentrations.

RELEASE NOTES FOR v2.1 (3-Apr-2008):
- Many, many bug fixes
- Photospheres and other refs handled correctly by hash interface
- Reworked Perl hash interface to eliminate stale pointers altogether
- Added Hilbert ditherer
- Better reconnection support
- Better auto-open support

RELEASE NOTES FOR v2.0 (1-Nov-2007):
- Now includes reconnection via the "reconnect" Flux::World method
- Updated and validated force laws
- Full plasmoid support
- Full open-field boundary support, including omega and U loop interactions with the boundary
- Includes a Floyd-Steinberg ditherer for footpoint placement
- Includes techniques ("ductions") for moving footpoints in time-dependent simulations
- Better control over relaxation parameters
- Emergence/cancellation support
- Better interaction with Perl:
- Support for all fields via the Perl hash interface
- No memory leaks
- No stale pointers