CodeRunner Command Line Manual

-------------CodeRunner Manual---------------

 Written by Edmund Highcock (2009)

NAME

 coderunner


SYNOPSIS

 coderunner <command> [arguments] [options]


DESCRIPTION

 CodeRunner is a framework for the running and analysis of large simulations. It is a Ruby package and can be used to write Ruby scripts. However it also has a powerful command line interface. The aim is to be able to submit simulations, analyse data and plot graphs all using simple commands. This manual is a quick reference. For a more tutorial style introduction to CodeRunner go to
 http://coderunner.sourceforge.net

 This help page documents the commandline interface. For API documentation see
 http://coderunner.sourceforge.net/api_documentation

 As is standard, <> indicates a parameter to be supplied, and [] indicates an option, unless otherwise stated.

EXAMPLES

 $ coderunner sub -p '{height: 34.2, width: 221}' -n 24x4 -W 300

 $ coderunner can 34 -U

 $ coderunner plot -G 'height:width;{};depth==2.4 and status == :Completed;height'

 $ coderunner st -ul

 $ coderunner rc 'p status' -U

COMMANDS

 Either the long or the short form of the command may be used, except in interactive mode, where only short form can be used.

 Long(Short) <Arguments> (Meaningful Options)
 ---------------------------------------------

 available_defaults_files(avd) (C) 
	List the defaults files for the code module.

 available_modlets(av) (C) 
	List the available modlets for the code module.

 cancel(can) (j,f,U,N) 
	Cancel the specified job.

 change_run_id(cri) <new_ids> (j,f,U,N) 
	Changes the id of a given set of runs to a new set of ids

 code_command(cc) <command> () 
	Call a class method of the run class. Effectively this will call run_class.class_eval(command). See documentation for whichever code module is in use.

 code_runner_execute(crex) <Ruby fragment> () 
	Run (within the CodeRunner class) the fragment of Ruby code given.

 concat(concat) <output file> (j,f,U,N) 
	Concatenates NetCDF output files together. File is output in the CR root directory.

 continue_in_new_folder(cnf) <folder> (j,f,U,N) 
	Make a new folder in the parent directory and copy all coderunner configuration files to that folder. If options j or f are specified, copy all matching runs to that new folder.

 delete(del) (j,F,U,N) 
	Permanently erase all filtered runs.

 differences_between(diff) (j,f,U,N) 
	Print a table of all the differences between the input parameters of the filtered ids.

 directory(dir) <id> () 
	Print out the directory for the given run.

 dumb_film(dfm) (F,G,g,U,N,j,f) 
	Create a film of the specified graphkits using gnuplot "dumb" ASCII terminal.

 execute(ex) <Ruby fragment> () 
	Run (at the top level) the fragment of Ruby code given.

 film(fm) (F,G,g,U,N,j,f) 
	Create a film of the specified graphkits.

 generate_cubecalc(gencc) () 
	Generate the file cubecalc.cc, the source code for the coderunner test program.

 generate_documentation(rdoc) () 
	Create automatic documentation using the rdoc tool (deprecated, use the command line tool ri for getting help, or see rubygems.org/gems/coderunner).

 generate_modlet_from_input_file(gm) () 
	Deprecated

 interactive_mode(im) (U,N,j,q) 
	Launch an interactive terminal. Any command line flags specified set the defaults for the session.

 load_file(ld) <script file> () 
	Load a Ruby script file using the CodeRunner framework.

 manual(man) () 
	Print out command line manual

 netcdf_plot(ncplot) <netcdf_file> <vars> <indices> (w) 
	Plot a comma separated list of variables, at a comma separated list of indices (nil for all) from the specified netcdf file against each other using gnuplot.

 parameter_scan(ps) <scan file> (n,W,k,v,p,T,d) 
	Read a parameter scan from file. For full details of how to write a parameter scan, see online documentation (coderunner.sourceforge.net).

 plot_graph(plot) (G,g,w,O,U,N,j,f) 
	Plot the specified graphkits using Gnuplot

 print_queue_status(qstat) (U,u) 
	Show the current status of the queue

 readout(ro) () 
	Print a simple text readout of all data from the runs.

 reference(ri) <ruby_class_or_method> () 
	Print out documentation for the given class or method. Documents classes, methods, constants and modules in the usual Ruby form: e.g. 

* CodeRunner -- a class
* CodeRunner.status -- a class method
* CodeRunner#filter -- an instance method
* CodeRunner::Run -- a sub class
* CodeRunner::CODE_RUNNER_VERSION --a constant


 resubmit(resub) (p,n,W,k,v,T,d,J,f,j) 
	Resubmit the filtered runs to be simulated. All parameters will be the same bar those altered by the p option.

 run_command(rc) <command string> (U,f,j,N) 
	Cause all filtered runs to evaluate the given string.

 runner_eval(ev) <command string> (U,N,j,f) 
	Cause the runner (the CodeRunner instance) to evaluate the given string.

 scan(scan) <scan string> (p,n,W,k,v,T,d) 
	Submit a simple scan. For full details of how to write a simple scan, see online documentation (coderunner.sourceforge.net).

 show_values_of(shvl) <expression> (U,N,j,f) 
	Evaluate the expression for each run and print a unique sorted list of them.

 start_launcher(launch) <refresh_interval> <max_queue_size> () 
	Start a simple job launcher for non batch systems.

 status(st) (U,N,j,f,O) 
	Print out a summary of the status of the filtered runs.

 status_loop(sl) (U,N,j,f,O) 
	Loop, updating the filtered runs, then printing out a summary of the status of the filtered runs. 

 status_loop_running(slr) (U,N,O) 
	Loop, updating and then printing out a summary of runs which are currently running.

 status_with_comments(sc) (U,N,j,f,O) 
	Print a list of ids with their status and any comments.

 submit(sub) (p,n,W,k,v,T,d,J) 
	Submit a run to be simulated.

 submit_command(subcom) <job name> <command> (n,W,v,T,d) 
	Submit an arbitrary shell command to the batch queue.

 write_graph(wg) <filename> (G,g,w,O,U,N,j,f) 
	Write a graph to disk.

 write_report(wr) (j,f,U,N) 
	Writes out a summary of a given run in a LaTeX document.

OPTIONS

--recalc-all -A
	Causes each directory to be reprocessed, rather than reading the cache of data. Its exact effect depends on the code module being used. By convention it implies that ALL data analysis will be redone.

--reprocess-all -a
	Causes each directory to be reprocessed, rather than reading the cache of data. Its exact effect depends on the code module being used. By convention it implies that VERY LITTLE data analysis will be redone.

--code -C
	The code that is being used for simulations in this folder. This string must correspond to a code module supplied to CodeRunner. It usually only needs to be specified once as it will be stored as a default in the folder.

--comment -c
	A comment about the submitted run.

--debug -d
	Submit the simulation to the debug queue. This usually only has meaning on HPC systems. It does not mean debug CodeRunner!

--defaults-file -D
	Specify a defaults file to be used when submitting runs. The name should correspond to file named something like '<name>_defaults.rb' in the correct folders within the code module. Every time a different defaults file is specified, a local copy of that defaults file is stored in the root folder. This local copy can be edited and all runs will use the local copy to get defaults. CodeRunner will never overwrite the local copy.

--film-options -F
	Specify a hash of options when making films. The most important one is fa (frame array). For example -F '{fa: [0, 200]}'. For all possible options see the CodeRunner method make_film_from_lists.

--conditions -f
	A string specifying conditions used to filter runs. This filter is used in a variety of circumstances, for example when printing out the status, plotting graphs etc. Example: '@height == 10 and @width = 2.2 and @status==:Complete'.

--run-graph -g
	Specify a run_graphkit to plot. A run_graphkit is one that is plotted for an individual run. The run graphkits available depend on the code module. The syntax is graphkit shorthand:
 -g '<graph_name>[ ; <graph_options> [ ; <conditions> [ ; <sort> ] ] ]'
 where conditions (i.e. filter) and sort will override the -f and -O flags respectively. The -g flag can be specified multiple times, which will plot multiple graphs on the same page.

--graph -G
	Specify a graphkit to plot. A graphkit combines data for every filtered run. The syntax is graphkit shorthand:
 -G '<axis1>[ : <axis2> [ : <axis3 [ : <axis4> ] ] ] [ ; <graph_options> [ ; <conditions> [ ; <sort> ] ] ]'
 where conditions (i.e. filter) and sort will override the -f and -O flags respectively. <axis1> etc are strings which can be evaluated by the runs. The -G flag can be specified multiple times, which will plot multiple graphs on the same page. For example
 -G 'width : 2*height ; {} ; depth == 2 ; width'
 will plot twice the height against the width for every run where the depth is equal to 2, and will order the data points by width.

--heuristic-analysis -H
	Should be specified whenever CodeRunner is being used to analyse simulations which did not originally submit (and which will therefore not have the usual CodeRunner meta data stored with them).

--use-component -h
	Specify whether to use real or component runs

--just -j
	Specify individual run ids. For example -j 45,63,128 is shorthand for -f 'id==45 or id==63 or id==128'

--job_chain -J
	Chain multiple simulations into one batch/submission job. Most useful for HPC systems.

--skip-similar-jobs-off -k
	Normally CodeRunner will not submit a run whose input parameters identical to a previous run (to avoid wasting computer time). Specifying the flag will override that behaviour and force submission of an identical run.

--loop -l
	Used with the status command. Keep continually printing out live status information.

--multiple-processes -M
	

--modlet -m
	Specify the modlet to be used in the current folder. Only needs to be specified once as it will be stored as a default.

--no-run -N
	On some machines getting a list of currently running jobs takes a long time. Specifying this flag tells CodeRunner that you definitely know that no runs in the folder are still queueing or running. Do not specify it if there are still running jobs as it will cause their statuses to be updated incorrectly.

--nprocs -n
	A string specifying the processor layout for the simulation. For example -n 46x4 means use 46 nodes with four processors per node. In the case of a personal computer something like -n 2 is more likely. The default is 1

--sort -O
	Specify the sort order for the runs. Used for a variety of commands, for example status. It is a string of semicolon separated sort keys: for example -O height;width will sort the runs by height and then width.

--project -P
	Specify the project to be used for billing purposes. Only necessary on some systems.

--parameters -p
	A hash of parameters for the simulation. For example -p '{height: 20, width: 2.3}'. These parameters will override the defaults in the local defaults file.

--queue -Q
	The name of the queue to submit to on HPC systems. Not yet implemented for all systems. Please submit a feature request if it is not working on your system.

--no-auto-create-runner -q
	Used for interactive mode when you don't want CodeRunner to analyse the current directory.

--terminal-size -t
	Specify the terminal size for situations where CodeRunner cannot work it out: -t '[rows, cols]' (square brackets are part of the syntax)

--test-submission -T
	Don't actually submit the run, but exit after printing out the run parameters and generating any input files necessary.

--use-large-cache-but-recheck-incomplete -u
	Use the large cache for speed, but check any runs whose status is not :Complete or :Failed.

--use-large-cache -U
	Use the large cache for speed. No run data will be updated.

--version -v
	Specify the version of the simulation code being used. Only has an effect for certain code modules.

--wall-mins -W
	Specify the wall clock limit in minutes.

--write-options -w
	Use when plotting graphs. A hash of custom options which are applied to the graphkit just before plotting it; for example: -w '{xlabel: 'X Axis Quantity, log_axis: 'y'}'

--executable -X
	Specify the location of the executable of the simulation code. It only needs to be specified once in any folder, unless it needs to be changed.

--other-folder -Y
	Run CodeRunner in a different folder. On a local machine 'coderunner st -Y some/other/folder' is identical to 'cd some/other/folder; coderunner st -Y'. However, this flag can also be used for remote folders using RemoteCodeRunner (as long as CodeRunner is installed on the remote machine). e.g. -Y username@machine.location:path/to/folder. If this option is specified multiple times, a merged runner will be created from the set of specified folders.

--supplementary-options -y
	

--server -Z
	Technical use only

--log -z
	Switch logging on (currently not working very well (05/2010)).

--replace-existing 
	Use with resubmit: causes each resubmitted run to replace the run being resubmitted.

--smart-resubmit-name 
	Use with resubmit: causes each resubmitted run to only contain its original id and changed parameters in its run name.

--submit-runner-index 
	Use with submit or resubmit when specifying multiple root folders... selects which runner will be used for submitting (i.e. which root folder the runs will be submitted in.