How To Read and Use Examples

Altogether there are more than 400 examples presented in this documentation (183 for FLAC3D, 59 for FLAC2D, 135 for 3DEC, and 37 for PFC). The information provided below provides a baseline for understanding examples as they are presented in the documentation and as they may be explored in the code.

Tip

It is strongly recommended that users load examples for examination in the code using the i Examples dialog while reading the corresponding example documentation.

Reading Examples

When reading an example, bear in mind that every example presents content following a uniform structure:

• problem statement,

• theoretical background (as needed),

• modeling approach,

• details of program mechanics necessary to construct the model (as needed), either in terms of writing the necessary data file(s) and/or constructing parts of the model with user interface tools,

• model execution and solution information (i.e., running the model in the code),

• examination of results,

• variation of the model (as needed/intended),

• further examination of results,

• references (as needed), and

• listing of principle data file(s) at the end of the example.

The following are additional considerations worth remembering when reading examples.

• Every example that appears as an example is provided as a project with the software. Every project so provided contains all necessary data files, FISH/Python script files, and any ancillary matter necessary to run the example in the code. Note results (*.sav files) are not provided with the project but are created when the example is run in the code.

• Every project is accessible for opening in the code via the i Examples dialog.

• Any snippet of commands that appear in the body text of an example is an excerpt from one of the data files included in the project.

• There are different types of examples, consequently the detail provided for each of the content structures listed above is different. For example, a tutorial, which focuses more on the mechanics of using the software, is usually quite light on theory but heavy on the program mechanics. Conversely, a verification problem, which by its nature exists to validate the code’s implementation of a theoretical aspect of its numerical modeling capabilities, will be quite heavy on theory. Example applications will likely have a greater amount of examination of results — and so on. An enumeration of example types, and their purposes, appears below.

Using Examples

This documentation and the example projects supplied with the software are complementary and are best understood when used together. The elements that appear in the example documentation to facilitate this are shown below.

Title

Figure 1: The title of the example appears at the top of the document page and may also be identified on the navigation tree to the left. If using an external browser, the title will also be used on the page tab in the browser.

The title of the example that appears at the top of the page is the name by which the example is found in the i Examples dialog.

Plate

Figure 2: The example’s plate indicates the example type with a reminder the project can be opened in the code.

Each example provides a plate with three components:

• the i type of example being shown,

• a reminder that the project encompassing the present example may be loaded into the code for which it was built (with a footnote reminding the user that the example project may be accessed from the i Examples dialog), and

• a link to this page on how to read and use examples.

Sidebars (as available)

Figure 3: The middle section of this page shows a sidebar – for an accompanying video, in this case – that points to additional content that elucidates the material presented in that section.

Some examples may have sidebars that point to additional resources that are available for understanding the material described in the current section or, in some cases, for the entire example.

Endnote

Figure 4: The endnote reminds users where to find the example project.

Every example concludes with the endnote reminding that the example project may be found and loaded in the code from the i Examples dialog.

Example Context

Examples appear throughout the documentation, in many locations. Identifying where the example appears on the navigation tree to the left provides important contextual clues as to the nature of the example. An example appearing in the verification section of the Thermal options for FLAC3D is going to be more specific, narrow, and of lesser generality than one of the practical engineering examples that appears on the code’s main Example Applications list.

The examples are not furnished a list of prerequisites — it is never suggested that a user first read one part of the documentation or a previous example before considering the example currently in hand. However, this means it is up to the user to observe the example’s placement on the navigation tree and understand what type of example it is (described next) so as to anticipate what can be learned from it.

Types of Examples

The many examples provided with the software serve a range of purposes. Some are oriented to teaching use of the software (tutorials), some are proofs of validity of the numerical approach (verification problems), some illustrate practical engineering applications (example applications), and so on. Whenever an example is presented in the documentation, the plate indicates the example type. Learning from the examples is accelerated when users keep in mind the type of example they are examining.

All examples comprise one or more data files that can be used to understand (and copy, as needed) command syntax and construction.

Example Applications

Example applications are problems that have been solved using the software, demonstrating the various classes of problems to which the programs may be applied. The problems represent only a sample of the potential range of applications for the software.

Verification Problems

The verification problems are tests in which the code solution is compared directly to an analytical (i.e., closed-form) solution. They are of less immediate use in a practical context, but can be valuable for illustrating the underlying theoretical principles at work in the software.

Model Verifications

This is a subset of the “Verification” category that is specific to examples used to validate constitutive models.

Logic/Feature Illustrations

These examples appear in the body text that introduces and defines a feature of the code. These examples tend to focus on illustrating how a particular feature is implemented and used within the context of the commands and keywords provided for it. These examples are not necessarily intended to produce real-world models but to illustrate how such models will need to implement the feature under discussion.

Tutorials

Tutorials are the optimal starting point for new users who want to work with the program right away. They present step-by-step instructions for working through the problems illustrated, and are focused on teaching program mechanics rather than theory or numerical modeling techniques.

Running an Example

When an example file is loaded from the i Examples dialog, first the example project is opened in a new instance of the appropriate/selected code, with the example documentation page loaded in the onboard help viewer in the program.

To run the example, locate the file “master.dat” and open it (double click on the file on the tree). Once loaded, press the run button () on the toolbar to run the example.