The python generator nbigen*.py writes the internal nbi_com (COMMON 
replacement) module and related modules and subroutines for NUBEAM.

--Author:  Douglas McCune, Jan-Feb 2002.

Input file:  nbspec.dat

  Contains names and descriptions for nbi_dimensions, nbi_com, and nbi_types.
  This file is internally documented by comments denoted by the "#" character.
  There are also comments denoted by the "!" character which describe the
  NUBEAM entities and which are to be copied into the generated output files.

  The nbspec.dat file is divided into four parts:

    Array_dimensions
    Inputs
    Internal
    Outputs

  Note that NUBEAM contains some hand maintained modules that are not
  generated by this system.  As of Feb. 2002, these are:  

    map_larmor_mod
    nbatom_mod
    nbi_random
    nbi_strline
    nbspline_mod
    xjasub_mod

  Of which, the module "nbi_random" contains the state of the random number
  generator, which must be recorded in the state file.

Output files:

    f90 module sources:

    nbi_dimensions_mod.f90 -- array dimensions for dynamically allocated 
       arrays (nbspec.dat specifies default values and "sanity" upper limits).
       The contents of this file are determined by data in the
       "Array_dimensions" section of nbspec.dat.  This module will 
       be private to NUBEAM.

    nbi_com_mod.f90 -- internal variables and arrays (formerly in COMMON) used
       in NUBEAM.  Contents determined by the "Inputs", "Internal", and
       "Outputs" sections of nbspec.dat.  Generally, arrays are dynamically
       allocated by generated code (see below).  This module will be private
       to NUBEAM.

    nbi_types.f90 -- "public" module describing compound data types used to 
       transfer data into and out of NUBEAM.  Contents determined by the
       "Inputs" and "Outputs" sections of nbspec.dat.

       Inputs:  a type is generated for each related group of controls or
       input profiles; a subroutine is provided to load an instance of the
       type with default values, which can then be modified by the NUBEAM
       caller; a subroutine is provided to receive the prepared type and
       transfer its contents to the appropriate internal variables and
       arrays in nbi_com.  Profiles are communicated using "xplasma" ids.
       An example code is generated for the benefit of NUBEAM callers.

       Outputs:  a type is generated for each related group of outputs of
       the NUBEAM calculation.  For each array of output profiles (in
       nbi_com) an array of "xplasma" ids is also allocated; the generated
       type is used to transfer these ids, as well as scalar outputs, back
       to the caller.

    nbi_alloc.f90 -- a subroutine to allocate, and set to default values,
       usually zero, all arrays that can be allocated once user supplied
       dimensions are available.

    nbi_alloc2.f90 -- some dimensions are not computed until after all
       user inputs have been received; arrays associated with such
       dimensions are allocated here.

    nbi_dalloc.f90 -- a subroutine to deallocate all nbi_com arrays;
       each statement "deallocate(xyz)" is protected by the appropriate
       test "if(allocated(xyz)) ...".

    nbi_init.f90 -- a set of routines, one for each input data type, to
       set default values in a user supplied instance of the type.

    nbi_set.f90 -- a set of routines, one for each input data type, to
       set values in nbi_com from a user supplied instance of the type.

    nbi_get.f90 -- a set of routines, one for each input data type, to 
       fetch values from nbi_com into a user supplied instance of the
       type; might be useful e.g. for updating.

    nbi_update.f90 -- a set of routines, one for each input data type
       containing updatable inputs, to set updatable values in nbi_com
       from a user supplied instance of the type.  Note that most inputs
       are not updatable and can only be set once at the beginning of 
       the run.

    nbi_state_io.f90 -- routines for saving and restoring the "state"
       of the NUBEAM Monte Carlo simulation.  The "state" consists of
       all dimensions and input variables plus a number of internal and
       output items as marked in nbspec.dat-- whatever is needed to make
       the calculation perfectly restartable.

    nbo_get.f90 -- a set of routines, one for each output compound data
       type, for fetching various subsets of the fast ion code output into
       a user supplied instance of the compound data type.  The output
       is likely to contain "xplasma id" integers, which point to spline
       profiles stored in xplasma.

and, for internal use of the fast ion code:

    nbo_clear.f90 -- clear all output items, including output xplasma ids,
       to zero, 0.0, blank, .FALSE. -- user does not have to call this,
       the Monte Carlo code will call this during initialization of a step.

    nbo_load.f90 -- load all non-zero profiles into xplasma; set all
       output xplasma ids.  The user does not have to call this-- it will
       be done as part of the step completion process.

while the following is just a bare list of all Monte Carlo code variables
defined in the modules generated by nbigen:

    nbi_allnames.dat
