Getting Started with the ONETWO Transport Code

SETTING UP YOUR ENVIRONMENT

The transport-MHD-coupled version of the ONETWO transport code currently runs on several Unix-based platforms. What follows is a quick guide to getting started.


    On CRAY A, CRAY K and SAS-SUN at NERSC

        in your ".login" file include the lines

            setenv ONETWO /tmp/work/u1435
            set path = ( other_directories $ONETWO/codes other_directories )

    On HYDRA, HELIOS, ONETWO and most other HPs in the Fusion Group at GA

        in your ".login" file include the lines

            setenv SFDATA /usr/local/disspla11/data/dsdf.dat
            setenv ONETWO ~freemanj
            set path = ( other_directories $ONETWO/codes other_directories )

    On USCWSA and USCWSE (DISSPLA-based graphics are not available):

        in your ".login" file include the lines

            setenv ONETWO ~freemanj
            set path = ( other_directories $ONETWO/codes other_directories )

AVAILABLE COMMANDS (all platforms unless otherwise noted)

    To invoke main codes

        onetwo
            gafit
            toray
            xplot
            fastcd
            curray  (presently available only on the CRAY A)
        preplt
        trplot
        nubplt
        eqplot

    To invoke support codes

        verdi
        ploteq
        psiplot
        fixbdry

    To invoke support tools

        detail
        run12
        plot12
        scan12
        inputs12
        summarize
        xview
        tekview
        cgmplot

Remember that graphics are available only where DISSPLA is licensed, namely on the CRAY A, and on the HP computers HYDRA, HELIOS and ONETWO.

USING RUN12

You can use the RUN12 command to run ONETWO. To get the syntax of this command, type "run12" and this is what you'll see:

  usage:  run12 [mode [-tmins] [-a"date_time"]] run_id inone eqdsk [other_files]

Better yet, type "run12 help" and you will get the following screenful on RUN12:

 "run12" is a command which simplifies the running of the ONETWO transport code.

  run12 [arg_1 [arg_2] [arg_3]] arg_4 arg_5 arg_6 [arg_7 [arg_8 [arg_9]]]

         arg_1 = execution mode specifier    (OPTIONAL; default: background)
               = foreground, fg, background, bg, batch, debug, or help

         arg_2 = time limit for batch mode   (OPTIONAL; default: -t$limit)
               = -tminutes   where minutes = CPU time limit in minutes

         arg_3 = start time for batch mode   (OPTIONAL; default:  now)
               = -a"time_specification"      (example: -a"4am friday")

         arg_4 = a unique identifier for run (example:            xyz)
                 (A subdirectory will be created with this name.)

         arg_5 = name of REQUIRED inone file (example:      inone.xyz)
         arg_6 = name of REQUIRED eqdsk file (example:  g012345.67890)

         arg_7 = name of OPTIONAL input file (default:       toray.in)
         arg_8 = name of OPTIONAL input file (default:       xplot.in)
         arg_9 = name of OPTIONAL input file (default:      curray_go)

Here are some examples of the use of RUN12:

    % run12            abc inone.abc g012345.67890
    % run12 batch -t90 def ~/onetwo/inone.ech ~/onetwo/eqdsk.ech ./toray.in
    % run12 foreground ghi inone.ghi g012345.67890 toray.in xplot.in curray.in
    % run12 background jkl ../inone.test ../eqdsk.test . . .
    % run12 bg         MNO inone.MNO eqdsk.MNO
    % run12 batch -a"10pm" tim $ONETWO/codes/inone.tim $ONETWO/codes/inone.tim

RUN12 will prompt for any omitted parameters, but since the last three files are optional, a carriage return will suffice if they are not to be used. The purpose of these files is to provide the name of the toray.in file in TORAY runs, the (optional) xplot.in file in XPLOT runs, and the curray_go file in CURRAY runs. Standard toray.in, xplot.in and curray_go files exist in the $ONETWO/codes directory - use a period to invoke any or all of these, as in the last example above. All of the pathnames of the input files are limited in length to 64 characters.

When you execute RUN12:

    - A subdirectory (named arg_3) below your current directory will be created.
    - The two, three, four or five input files will be copied there.
    - A process running ONETWO will be started in the foreground.
      or
    - A process running ONETWO will be started in the background.
      or
    - A process running ONETWO under the symbolic debugger will be started.
      or
    - A job     running ONETWO will be put into the appropriate batch queue.

Note that specifying background mode explicitly will cause you to be notified upon run completion. All input and output files, including the screen capture log file (foreground, background and batch only) named onetwo.log, will end up in the subdirectory created for that run, thus allowing several concurrent ONETWO runs.

Note also that you need not use RUN12 to run ONETWO - you can simply run ONETWO like any other program, entering the name of the executable file onetwo on the command line. However, you are then responsible for managing all the execution details - particularly in the case of batch jobs, that can become cumbersome. Also, interactive processes may be limited in CPU time, so batch may be necessary for large jobs. (On the CRAYs, you can, however, use the UNICOS command "cpulim" to change your interactive cpu time limit.)

USE OF PRE- AND POST-EXECUTION TOOLS

The format of the "inone" file is essentially the same on all platforms, except that comments delimited by a semi-colon ";" (as on the CRAYs) may not be used on the HPs. The command "detail" may be used to strip out such comments:

    detail inone.old > inone.new

If you use RUN12 to run ONETWO, the above is done for you automatically prior to execution.

Once your ONETWO run has completed, you may want to issue the "scan12" command, which scans the main output file "outone" for the text "NaN" - if present, a serious error must have occurred in the execution. (Note that the absence of this characteristic text does NOT ensure the correctness of your run.)

You may also want to issue the "summarize" command. This will extract the summary section of the outone file into a separate - and much smaller - file named "summary", which may be browsed with "more" or other Unix filters, or perhaps with an editor.

GENERATING CGM METAFILES

Once ONETWO has completed executing you may generate plots using one or more of the programs in the graphics package. (If RF with plotting was turned on in the ONETWO run, you will already have run XPLOT to generate some plots from TORAY's output.) The procedure for using the plot package is shown schematically below:

    data file trpltout -------- program trplot --------> CGM file trplot.cgm
    data file bpltfil  -------- program nubplt --------> CGM file nubplt.cgm
    data file eqpltfil -------- program eqplot --------> CGM file eqplot.cgm

In practice, simply enter the name of the plot program to run and the corresponding CGM metafile will be generated. If there are many plots to make you will probably want to run the program in the background or batch.

PLOTTING CGM METAFILES: BASICS

The gplot CGM metafile translator is used to process metafiles produced by the ONETWO family of codes. The resulting plots may be viewed on your terminal screen (or emulator, such as VersaTerm, MS-Kermit, XTERM) if it supports the ubiquitous Tektronix 4010/4014 graphics:

    % gplot -q -S -stek4010 trplot.cgm            # CGM file -> Tek 4010 screen

or on an X Window System display (after having set your DISPLAY variable):

    % setenv DISPLAY your_IP_number:0             # set DISPLAY variable
    % gplot -q -S -sXWS trplot.cgm                # CGM file -> X display screen

CGM files can also be converted to PostScript format and piped directly to a PostScript printer. For example:

    % gplot -q -S -dPS trplot.cgm | lpr -Plps4    # CGM file -> printer (CRAY)
    % gplot -q -S -dPS trplot.cgm | lp  -dlps4    # CGM file -> printer (HP  )

PLOTTING CGM METAFILES: SHORTCUTS

Instead of using the very first gplot command shown above, one may take advantage of the tekview script (enter "tekview" for usage, "tekview -h" for more detail) to make viewing of CGM files on Tek 4010 screens relatively effortless. Then the viewing is done this way:

    % tekview trplot.cgm [ more CGM files ]       # CGM file -> Tek 4010

Likewise, instead of using the second gplot command shown above, one may take advantage of the xview script (enter "xview" for usage, "xview -h" for more detail) to make viewing of CGM files on X Window System display devices relatively effortless. Then the viewing is done this way:

    %   xview trplot.cgm [ more CGM files ]       # CGM file -> X Window display

For hardcopy, one may take advantage of the cgmplot script (enter "cgmplot" for usage, "cgmplot -h" for more detail) for easily translating CGM metafiles to PostScript and sending the output to a printer:

    % cgmplot -p lps4 trplot.cgm [ more CGM files ]     # CGM file -> printer