ugshell

Table of Contents

• Command-Line Options
• Interactive Shell
  • Auto Completion
• Runtime Information
• Debug Shell

For any questions, contact martin.rupp@gcsc.uni-frankfurt.de.

---

Command-Line Options

ugshell has the following build-in command-line options:

• -outproc id — Sets the output-proc to id. Default is 0.
• -ex scriptname — Executes the specified script.
• -noquit — Does run the interactive shell after specified script.
• -noterm — Terminal logging will be disabled.
• -logtofile filename — Output will be written to the specified file.

Note

There is bash completion available for ugshell, see BASH Tools.

Script files are written in LUA, see Scripting Tutorials for an introduction.

You can also use the command line to pass arguments to your scripts:

./ugshell -ex tutorials/tut02_loading_a_domain.lua -grid unit_square/unit_square_quads_2x2.ugx  

You can access command line parameters by using the lua function from util.lua:

function util.GetParam(name, return_if_unavailable)

For that, you have to include the ug_util.lua file using ug_load_script("ug_util.lua").

ug_load_script will search for files in the following directories (in that order)

• relative to current script
• as absolute filename
• in the scripts path
• in the apps path
• in the ug4 path.

  Note

  ug_load_script will load files parallel, so you have to be sure that all processes are calling ug_load_script. if you want to load a different file or files only on some cores, you can use ug_load_script_single.

  Example:

  ug_load_script("ug_util.lua")
  gridName = util.GetParam("-grid", "unit_square/unit_square_quads_8x8.ugx")

  You can find out more about provided scripts in Provided LUA Scripts.

If there is no commandline argument "-grid", then the second argument is returned by util.GetParam. Otherwise, the argument after "-grid" in the commandline is returned. Notice that omitted parameters to Lua-functions are treated as nil, so util.GetParam("-grid") is the same as util.GetParam("-grid", nil). If you want your argument to be casted to a number, use util.GetParamNumber:

function util.GetParamNumber(name, return_if_unavailable)

If the argument is not a number, the second argument is returned. To check if an option is in the command line, use util.HasParamOption:

function util.HasParamOption(name)

Examples:

dim = util.GetParamNumber("-dim", 2)
useAggressiveCoarsening = util.HasParamOption("-AC")

You can abort the execution of ug4 out of Lua scripts by using exit(). If you want to stop the execution of a script at a specific place, but you want to use the interactive shell thereafter, insert at that place a call like error("break") (or whatever message sounds reasonable to you) and start the run with the -noquit. option

---

Interactive Shell

When starting ugshell without arguments, you get the following output:

ug:> 

and a blinking cursor: This is called the interactive shell. Interactive shell is disabled when you use -ex without -noquit and if ug4 is running in parallel.

In the interactive shell you can do everything just like in a .lua file, for example: <scriptname> (as usual) by executing ug_load_script():

ug:> ug_load_script(<scriptname>)

Auto Completion

The interactive ugshell has some auto-completion features implemented. When you enter a part of something and hit tab ugshell tries to auto-complete your input. If there is not a unique completion, and you hit tab again, you get a list of possible completions.

• Path Completion:
  "../scr" -> "../scripts/"
  (only tried if the word left from the cursor starts with a ")
• Member Function Completion:
  mainProfileNode:cal -> mainProfileNode:call_tree
  (only tried if there is a : in the word)
• Table/"Namespace" Completion:
  math.e -> math.exp
• Completion of Lua globals, internal functions and modules (like math, io, string), classes and global functions from the ug4-registry, and functions defined in Lua script.

---

Runtime Information

You can get Information about the current state of Lua by the following methods:

• void TypeInfo(const char *typename)

  TypeInfo prints all information available for the data you insert. Note that you have to enclose your type name with "</tt>. Example: <tt>TypeInfo("Grid"). TypeInfo works with
  • tables, and prints their content recursively
  • all other basic lua types: numbers, strings, ...
  • lua script functions, and prints their code
  • classes, global functions and member function from the ug4-registry
• In interactive shell, the use of TypeInfo can be abbreviated by using

  ug:> Grid?

  and hitting enter. When the name left to the cursor is unambiguous, hitting tab three times also displays information about the object. Functions show their parameters when you enter the function and the first bracket

  ug:> GetProfileNode(

  and hit tab.

• void ClassUsage(const char *typename)

  ClassUsage prints the usage of the class, that is:

  • Functions returning an instantiation of the class
  • Functions which require one argument to be of the type of the class or of a base class
  • Instatiations in Lua which have the type class or a subclass of the class.

  Example (excerpt):

  ug:> ClassUsage("Domain2d")
  
  --- Functions returning Domain2d: ---
   Domain2d* IApproximationSpace2d:domain()
  --- Functions using Domain2d: ---
   bool Domain2d:LoadDomain (Domain2d* Domain, string Filename, integer Number Refinements)
   bool Domain2d:DistributeDomain (Domain2d* )
   IRefiner* Domain2d:GlobalDomainRefiner (Domain2d* )
   Domain2d:TestDomainInterfaces (Domain2d* )
   IApproximationSpace2d:assign_domain ([Domain2d* ])
   DirichletBND2d:set_domain ([Domain2d* ])
  
  Instantiations of Class Domain2d:
  dom        (Domain2d)

• Listing

  • list_luaObjects() : Lists all Objects created by lua or in lua scripts.
  • list_cfunctions() : Lists all global functions provided by the current registry.
  • list_classes() : Lists all Classes provided by the current registry.
  • list_scriptFunctions() : Lists all LUA functions provided by you or loaded scripts.
  • list_internalFunctions() : Lists all functions (these are also internal registry or lua functions).
  • ls() lists all of the above.

  ---

Debug Shell

You can also debug your Lua Script using the shell. For this, you can use the script functions

• breakpoint()

  breakpoint() breaks the execution of the script at exactly the location it stands. This is the preferred method of setting a breakpoint.

• breakpoint(source, line)

  breakpoint("laplace.lua", 69) adds a breakpoint at the file "laplace.lua" (path relative to current script). print_breakpoints prints those. Note that only lines with code are "catched" by the compiler.

When your breakpoint is reached, you are entering the ug4 debug shell:

./../scripts/laplace.lua:69 breakpoint()
debug:> 

The debug shell is like the normal ugshell (so it has Auto Completion and Runtime Information), but you have some extra commands. Most of them have a similar function as in gdb:

• continue, cont — Continues execution.
• step — Continues execution until the next line is reached, steps into subroutines.
• next — Continues execution until the next line is reached, does not step into subroutines (that is, we are skipping lines with greater function stack depth).
• finish — Finishes subroutines/scripts (continues execution until a line is reached with lower function stack depth).
• list — Lists the script surrounding the current statement.
• backtrace, bt — Prints the function stack.
• up, down — Goes up and down the function stack.
• quit, exit — Like in normal shell, exits ug4 directly.
• print VAL — Like VAL?

Note that you don't have to configure ug4 with cmake -DDEBUG=ON ..) to use the debug shell. There is a small performance drawback when using breakpoint(source, line) because we have to check for every line if it is a break line. This is especially the case if you have lots of small calls in your Lua script. However, there is no performance drawback in breakpoint().