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