Commands, a Rationale

At this juncture, users who have reviewed the preceding material should have a good working understanding of program commands and how to use the Console pane to issue them. However, it may not be entirely clear why the program is designed to utilize commands this way in the first place. The following discussions are provided to give insight into this question.

Why A Command-Driven Interface?

Whether generated interactively or manually, the basic description of any UDEC model is a data file. A data file is a standard text file containing commands that completely specify a UDEC model, from model creation to additional sequential operations required to undertake physical simulations.

At first exposure, the fact that UDEC uses data files to describe the model may seem antiquated, perhaps a relic of 1970s program design. To the contrary, this form of model description has proven to be quite valuable and is considered an integral part of what makes UDEC, and Itasca codes in general, powerful modeling tools. As our user interface design matures, our goal is not to remove the command-driven interface but, instead, to simplify its use, making simulations easier to undertake while retaining the flexibility this design embodies.

Below are a few reasons that using a data file description is advantageous.

  • Compact representation

    Even the most complex models can be created by a set of data files that are generally not more than a few hundred lines in length. In fact, the vast majority of models are far smaller. This fact means that the complete description of your UDEC model resides in a text file that is only a few kilobytes in size. As a result, it is trivial to share your model with others, email it to Itasca for support, archive your model for future reference, and use versioning software to track changes.

  • Repeatability

    Itasca works very hard to ensure that the same version of the code and the same data file will always produce the same result to machine precision. This means that when you send Itasca, your colleagues, or your clients a data file, you know that the result will be unchanging. Thus it is not necessary to archive the complete results of a modeling effort, which may be many gigabytes of save and result files. Instead, one can just retain the data file and the code version used to execute it.

  • History and Path Dependence

    Except for the most trivial models using the simplest of materials, the path used to reach the solution is a very important part of the model description. A data file allows the sequence of events to be described clearly and flexibly. Many programs may offer excavation sequence options, but the data file allows any sequence of events to be made if necessary. This includes changes to boundary conditions, changes to material properties, changes to fluid interactions, etc. as well as changes to the excavation sequencing. If one were to design a graphical user interface to include the entire list of options available via a data file, the result would be complex, requiring clumsy tools to edit and change.

  • Flexibility

    The data file allows the user maximum flexibility in how they choose to create and process a model, including the order in which things are specified. While there is a standard sequence of simulation steps recommended for simple models (e.g., geometry creation, naming of regions, material and property specification, boundary conditions, initial conditions, solving, excavating, solving, etc.), every model is different. Often complex models require modifications to the standard simulation progression. Itasca is committed to the idea of not constraining users to a small set of simulation options, providing users with the ability and tools to undertake physical simulations in the way they see fit.

  • Scripting

    The ability to combine model-creation commands with scripting in UDEC is tremendously powerful. For instance, an entire class of models can be investigated by trivially changing a set of initial parameters within a data file. Application of complex sequences, geometries, property distributions, etc. may be automated with a script in a way that would be very time consuming and difficult to replicate in a traditional graphical user interface. In addition, in-depth model querying and the inclusion of new physical phenomena, not included in UDEC, can be introduced via user-created scripts that execute during cycling.

The downside to such a command-driven interface is that it can be imposing for new users, who may have the impression that mastery of a large number of complex commands is necessary to undertake the simplest of modeling efforts. In truth, the learning curve is faster than being confronted by a complex graphical user interface that has numerous tools with a plethora of buttons in different panes—something we have all experienced. The commands have been purposefully structured using descriptive and consistent terminology, making it easy to read a data file and understand the operations it invokes. In addition, interactive command documentation is available as you create and edit a data file from within UDEC, simplifying the process substantially.

In order to make creating and editing data files as easy as possible, UDEC contains the following features:



FISH is a built-in scripting language that gives the UDEC user powerful control over most every aspect of program operation. FISH is short for “FLAC-ISH” (or the language of FLAC), the code for which it was first developed. Now, in addition to FLAC, FISH is also integrated into all Itasca commercial programs.

FISH is embedded deeply into UDEC at nearly every level. It can be used to parameterize data files so that a number of varying cases can be built into the same basic model. Every data type that makes up a UDEC model is also available for FISH to manipulate directly—before, after, and during the solution. This means that not only can FISH be used to create custom complex models and customized results, it can also be used to add custom physics to the solution process that is not part of the standard package.

FISH includes constructs to embed UDEC commands within FISH functions (see the command – end command block in the example shown in the Run Control section). parenthetical here awkward, unsure of how to edit?

FISH is a semi-compiled language that uses dynamic typing for variables – syntax and use is similar to (but not exactly the same as) Python. It has been created to be very simple for small needs, but it provides structure and data types needed to support large and complex programs if necessary.

The following illustrations give just an idea of the power of FISH. More complete information is available in the sections Tutorial: Working with FISH and FISH Scripting. Examples below are given to represent five general areas of application:

  • Model Creation
  • Parameterization
  • Custom Visualization
  • Physics Extension
  • Run Control