# I2MEX Compilation on PPPL Flux

I2MEX is compiled on PPPL Flux using the existing TRANSP build environment and TRANSP library ecosystem.

## Build Environment

Start from the top-level I2MEX source directory.

First purge any currently loaded modules:

```bash
module purge
```

Source the TRANSP environment:

```bash
. ../transp_so/environ
```

The TRANSP environment defines the compiler, external dependencies, and the common build location through `$LOCAL`.

The current build location can be checked with:

```bash
echo $LOCAL
```

The I2MEX environment variables can also be checked with:

```bash
echo $I2MEX_HOME
```

## Set TRANSP_ROOT

I2MEX uses libraries from the existing TRANSP build. Set `TRANSP_ROOT` to the build location defined by the TRANSP environment:

```bash
export TRANSP_ROOT=$LOCAL
```

Verify it with:

```bash
echo $TRANSP_ROOT
```

At this point:

```text
LOCAL       = TRANSP build/install location
TRANSP_ROOT = TRANSP build/install location
```

I2MEX will therefore use the existing TRANSP libraries under:

```text
$TRANSP_ROOT/lib
```

## Enable Shared Libraries

Set:

```bash
export MAKE_SO=1
```

This enables creation of the I2MEX shared library in addition to the static library.

## Compile I2MEX

From the top-level I2MEX source directory, run:

```bash
make -f Makefile_flux
```

The complete compilation sequence is therefore:

```bash
module purge

. ../transp_so/environ

echo $LOCAL
echo $I2MEX_HOME

export TRANSP_ROOT=$LOCAL
export MAKE_SO=1

make -f Makefile_flux
```

## Build Products

The I2MEX libraries are installed in:

```bash
$LOCAL/lib
```

They can be checked with:

```bash
ls -l $LOCAL/lib
```

In particular, the build should create the I2MEX library under this directory, including `libi2mex.so` when `MAKE_SO=1`.

The I2MEX executables are installed in:

```bash
$LOCAL/bin
```

They can be checked with:

```bash
ls -l $LOCAL/bin
```

Thus the build uses the same installation tree as the sourced TRANSP environment:

```text
$LOCAL/
├── bin/        I2MEX executables
├── lib/        libi2mex and TRANSP libraries
├── mod/        Fortran module files
└── obj/        object files
```

## Quick Build Procedure

For subsequent builds, the required commands are:

```bash
module purge
. ../transp_so/environ
export TRANSP_ROOT=$LOCAL
export MAKE_SO=1
make -f Makefile_flux
```

After compilation:

```bash
ls -l $LOCAL/lib
ls -l $LOCAL/bin
```

This build configuration intentionally uses the existing TRANSP environment and TRANSP libraries rather than attempting to build all TRANSP dependencies independently inside the I2MEX repository.


I2MEX: ideal 2-d Magnetohydrodynamic Equilibrium on Xplasma
===========================================================

I2MEX, by providing a standard equilibrium representation, allows stability
codes to obtain metric information from a variety of equilibrium sources.
These include GEQDSK (EFIT format), INP1/inp1.cdf (CHEASE), eqdsk.cdf (JSOLVER)
as well as TRANSP run data stored on local file system or in the MDSPlus tree.

I2MEX is based on a minimal set of data: the scalar pressure, safety factor, 
covariant toroidal B field plus the (X, Z) coordinates which are loaded-in at 
initialization. All metric quantities are computed on the fly on arbitrary, 
user-specified grids (poloidal angle, poloidal flux/2*pi), using bi-cubic splines.

A. Pletzer (pletzer@pppl.gov)

1) Installation
---------------

See INSTALL file. 

Normally all you have to do is 

gmake all

This will by default install a library under ../<platform>/lib and a test executable
 ../<platform>/test/i2mex

Please check that your LD_LIBRARY_PATH variable points to the location of your
MDSPlus library. Eg, 

setenv LD_LIBRARY_PATH /usr/local/mdsplus/lib:${LD_LIBRARY_PATH} 

under csh, or

LD_LIBRARY_PATH=/usr/local/mdsplus/lib:${LD_LIBRARY_PATH}
export LD_LIBRARY_PATH

under bash, sh, and ksh.


2) Test run
-----------

The various supported equilibrium input formats can be checked by running 
 ../<platform>/test/i2mex. You will need to have the following files accessible:
INP1, inp1.cdf, g*. To test the MDSPlus capability you will also need permission
to enable MDSPlus access (contact your local administrator). 

The test program i2mex will dump 3 files: drive.mtv, gserror.dx and mapdsk.cdf
which can be used to visualize the results. 

If you have plotmtv installed type 

plotmtv drive.mtv

To see the error of the Grad-Shafranov solution using openDX type

export DXDATA=`pwd` (or equivalent under csh)
dx &
(then select run "Run visual program")
(select "gserror.net")


The content of mapdsk.cdf can be viewed through matlab, type:

matlab
mapdsk
(you will need the netCDF toolbox to be installed, modify mapdsk.m to change 
this location if necessary).


3) mex2eqs
----------
   retrieve and map equilibrium data for postprocessing by EQS,
   the front end to ORBIT
   Note: you can not use the included inputfiles for the i2mex test program. 
 
4) Documention
--------------

All methods are documented in index.htm

Good luck!

alexander.pletzer@nesi.org.nz