IRIS user manual

As explained above, IRIS depends on several external — some of them optional — libraries which enable special type of computations. We describe each of them indicating what type of capabilities they enable and some instructions for their installation. The source files for the libraries are not distributed with IRIS, but mut be downloaded directly from the internet and installed in user-readable directories. It is not easy to explain all the possible solution for different machines and operating systems: IRIS makefile is simple enough to allow for customization.

The following table summarizes the requirements for external libraries

The final stage consists in building the finite element code IRIS and linking it with all the external libraries. The code ships with a makefile that should take care of all the building process (see the Appendix).

The building process starts by selected which optional modules should be linked with the code.

After uncompressing the files, issuing the command make should take care of everything and build the final binary. If the building process fails, one should look into the makefile, and modify it to suit the computer needs.

If the building process completes, a binary iris will be created. The user then needs to move it to a directory in the correct path, such as /usr/local/bin.

IRIS is started from a terminal by the command:

iris [--help] [–-debug] [--libraries] [--save] [-–test] [-–threads t] 
     [-–version] [filename]

The arguments can be entered in any order and are all optional. Their use is as follows:

• filename is the name (and path) of the analysis file, can be avoided if there is only one file with extension .iris in the directory where IRIS is run.
• help: Displays the complete list of (optional) arguments to the IRIS command.
• debug: Activates debug messages in runtime. This option is useful to track the flow of the program and help to identify possible errors. In addition, when the debug option is activated, the amount of data written in the IRISlog file will be increased.
• libraries: Returns a list of all the libraries linked with IRIS.
• save: saves the log file of the previous IRIS run so that it is not overwritten when running again.
• test: forces IRIS to run a suite of tests that verifies element, materials, mesh functions, etc. The full syntaxis of the command is:

iris –-test all | cad | elements | materials | solvers |
       topology | math | meshing

Errors in the tests are shown in the console and no messages are dumped if all the tests are passed.

• threads: IRIS is designed to run in multiprocessor computers. By default, the code selects an optimal number of threads into which the processing effort is split. However, the user might want to limit the resources available to the code by using this option. If t is larger than the number of cores available at runtime, this option is ignored.
• version: IRIS shows its version and exits.

The input file describes the fundamental characteristics of the analysis such as its name, its type, the integrator, the solver, the materials, the element types, etc. Each of these options is defined through lines of commands, which are just assignments separated by commas:

<command> [, <command>] [, <command>] [, <command>] [, ...]

Each <command> is an expression of the form:

<keyword> = <value>

where <keyword> is an alphanumeric string without quotes and <value> might be numeric, alphanumeric or a string delimited by single or double quotes. Symbolic expressions can be given within quotes, such as in

radius = "sin(4.0*_pi)+log(43.25*sqrt(10.0))"

A line ending with a backslash character \ indicates that the command is continued in the following line. A command can span as many lines as needed, as long as each line (except the last one) is terminated with the continuation character. The program does not distinguishes lower or upper case, except for data in strings. The character #, and everything coming after it until the end of the line, is ignored, thus serving to introduce comments in the input file.

A command line is recognized by its first keyword. In most cases, the order in which the remaining commands are input is not relevant. A few exceptions exist, mostly due to the need to introduce pairs of data. For example, in the tabular scaling factors, a sequence of pairs \((t_i,f_i)\) might be given to indicate the time evolution of a function in tabular form. In this case, and in some others, the value of the function is linked to the time instant prior to it.

Some of the commands are mandatory and some are optional. Generally speaking, the input file serves to create the model, run some type of analysis on it, and finally generate output data than can be postprocessed using external software (more on this later). Strictly speaking, the ordering of the commands is irrelevant since IRIS first reads all of them and later process them according to the most logical order (fist the geometry, then mechanics, finally the output).

The program IRIS is distributed with a directory of examples that illustrate all the capacities of the code. In this directory, subdirectories are included whose names refer to the commands or facilities illustrated by the specific example.

IRIS is a command-line code that takes a text file as input, creates a model and runs an analysis based on it. The code provides a log file with all the details of the analysis and — optionally — creates all the necessary files for the graphical postprocessing of the results and additional text files with specific output data of the solution. Figure 1 illustrates this overall structure in its simplest form.

./figures/flow-1.pdf

As previously indicated, the input file is responsible for describing completely the analysis that IRIS must perform when executed. It is based on a language that has been evolving through the years to include, at the moment, a wide range of possibilities as we will describe in subsequent chapters. The IRIS parser reads the input file and the sorts its content to obtain all the information required to run the analysis. Hence, there is a fair amount of freedom in the order with which the analysis is described. Figure 2 describes the main sections of the input file, ordered in a standard fashion.

./figures/input-1.pdf

In the following chapters, each of these blocks will be described with detail

The GUI is started from the gui directory of the distribution:

python3 gui/iris_gui.py [--host HOST] [--port PORT] [--no-browser]

By default it binds to 127.0.0.1 on an available port and opens the page in the system’s default browser; --no-browser starts the server without doing so. The server looks for the iris executable using the IRIS_EXECUTABLE environment variable, then ~/bin/iris or ~/bin/debugiris, then the system PATH.

The window is organized into tabs: Design, Run, Postprocess, Loggers, Files and Manual.

The Design tab is the preprocessor: it builds an .iris file interactively and keeps a live 3D preview of the model in step with it. Collapsible sections on the left cover the same ground as the input file itself — analysis and solver settings, geometry and mesh, materials and element types, boundary conditions and loads, output loggers, and a free-text area for any directive the builder does not yet expose. A Split=/=Builder=/=Source toggle controls how much of the raw generated .iris text is shown alongside the forms; Source mode allows editing the text directly, and an Update builder button re-parses it back into the forms.

The Run tab saves the current input, launches iris on it as a background process, and streams iris.log into a console as the analysis proceeds, with elapsed time and exit status. The run can be stopped at any time; when it finishes, any new .pvd, .vtu, .dof or similar output files are picked up automatically and offered for inspection in the Postprocess and Loggers tabs.

This tab renders the actual results of a completed analysis (Section 2.3): the mesh in the postprocessing files, colored by any nodal or elemental field, with a real, orbiting 3D camera (rotate, pan, zoom, and a perspective/orthographic toggle) rather than a flat plot. A slider deforms the mesh by the current displacement field, timesteps of a .pvd collection can be stepped through or played back as an animation, and the current view can be exported as a PNG or PDF (each export is saved next to a small Python script that reproduces it, per the convention described in Section 2.3).

The Loggers tab plots the numeric history files produced by output directives (Section 8) — reaction forces, energy, scaling factors, and the like — and can export the plot the same way as the 3D viewer. The Files tab browses example inputs, meshes and result files already present in the working directory or the IRIS distribution. The Manual tab embeds this document.

Let us start by mentioning, once again, that comments are available in the IRIS input file: everything after the character ’\’ is ignored by IRIS parser and does not even appear in the log file. For this reason, many input files — for instance, the ones in the examples directory of IRIS’ distribution — start with a block of the form

# block.iris
# Transient simulation of a hyperelastic block
# author: i. romero
# creation date: 1/7/2022

In addition to choosing the type of analysis that IRIS must run, users may define global parameters that can be later employed in the input file. By using the command constants, new alphanumeric paramters can be introduced that can later be used as arguments for other commands such as material contants, mesh dimensions, time step size, etc. The syntax of these definitions is

constants, <name> = <value> [, <name> = <value> ] [...]

Like everything other command in IRIS, constant names are case-insensitive. Values can be numeric or symbolic; in the latter case, the symbolic expression must be enclosed in quotes and may contain previously defined constants. The constants command can be used as many times as desired, and in any place of the input file.

In some instances, it might be useful to output messages to the screen while running IRIS. The command echo provides precisely this functionality and its syntax is:

echo, <string>

IRIS allows users to split the input file among several text files. The main file, the one that is sent in the command line to IRIS, can include all the necessary blocks by using the include command. Its syntax is:

include, file = <string>

This analysis type computes the dispersion diagram of a periodic medium: the branches of natural frequency \(\omega\) as a function of a wavevector \(k\) swept along a path in reciprocal space. A Bloch/Floquet reduction of the periodic unit cell is combined with a generalized eigenvalue problem \((K(k)-\omega^2 M(k))\,\phi=0\), solved at each sampled wavevector.

The command line is of the form

analysis, type = dispersion, geometry = [1d | 2d | 3d | frame2d]
    [, nbranches = <integer>] [, npoints = <integer>]
    [, structure = yes | no] [, solver = <keyword>]

geometry selects how many degrees of freedom per node enter the reduced eigenproblem: 1d and 2d keep only the first one or two translational components, 3d keeps all three, and frame2d keeps the two in-plane translations plus the out-of-plane rotation, for planar beam/frame lattices. nbranches is the number of frequency branches (lowest eigenvalues) reported at each wavevector, and npoints the number of wavevectors sampled along the path described next. structure selects the eigensolver: yes (the default) reduces the problem to a sparse operator and solves it by subspace iteration (the linear solver used internally defaults to pcg and can be changed with solver); no assembles the reduced matrices explicitly and solves the dense generalized eigenproblem with LAPACK.

The wavevector path. \(k\) is swept, in npoints equally-spaced steps, along the piecewise-linear path defined by two or more wavevector command lines, for example

wavevector, kx = 0.0, ky = 0.0, kz = 0.0
wavevector, kx = "+_PI", ky = 0.0, kz = 0.0
wavevector, kx = "+_PI", ky = "+_PI", kz = 0.0

Each line is a vertex of the path; with two vertices the path is a single segment, with more it visits every vertex in order. Components can be plain numbers or quoted expressions, in which case the symbolic constant _PI (\(\pi\)) is available, which is convenient to describe the boundary of the first Brillouin zone (e.g. from kx = "-_PI" to kx = "+_PI").

Periodicity. The medium’s periodicity is described with the usual periodicbc command (see the Periodic boundary conditions section), adding the keyword bloch = true:

periodicbc, body = <string>, \
     master = <string>, slave = <string>
     [, master = <string>, slave = <string>]
     [, master = <string>, slave = <string>], \
     bloch = true

With bloch = true, the master/slave node pairs identified by periodicbc are used to build, at every sampled wavevector, the Bloch reduction operator that writes each dependent (“slave”) node’s motion as its corresponding free (“master”) node’s motion times the phase factor \(e^{ik\cdot\Delta x}\), instead of being turned into linear multipoint constraints as is done for the ordinary (non-Bloch) use of periodicbc; multipoint constraints would not make sense for an eigenvalue problem. No macroscopic strain (epsxx, etc.) should be given in this mode.

Output. Results are written, one line per sampled wavevector, to the file iris.wk: the columns are \(k_x\), \(k_y\), \(k_z\) followed by the nbranches frequencies \(\omega\) (not \(\omega^2\)) at that wavevector, sorted from lowest to highest.

A note of caution. The default iterative eigensolver (structure = yes) can occasionally fail to converge on small or highly degenerate reduced problems — near-zero acoustic branches close to \(k=0\) are a common trigger — and will then silently report spurious zero frequencies rather than raising an error. If a dispersion diagram looks physically implausible (e.g. not symmetric in \(k\)), repeat the run or set structure = no to cross-check against the dense LAPACK solver.

See examples in 16_Dispersion.

This analysis type calculates the eigenvalues and eigenvector of a stiffness or the generalized eigenvalues for a dynamical problem. The commands in the command line are:

In this analysis, IRIS finds the nmin smallest eigenvalues and eigenvectors of the stiffness matrix using the subspace iteration method. When the keyword generalized is included, this type of eigenpairs are calculated instead of the standard ones.

IRIS can be employed to ascertain the well-posedness of a discretization by calculating and writing to disk the main operators that define the problem and its norms. The command line of this type of analysis is of the form

analysis, type = infsup, primal = <string>, dual = <string>

To understand what the analysis does, consider first a irreducible formulation of small strain solid mechanics in which the only variable is, for example, the displacements u. Then, the inf-sup analysis will be launched with the command line

analysis, type = infsup, primal = "u"

The analysis will calculate the stiffness matrix of the problem and write it on the file K.hwb, a sparse storage format known as Harwell-Boeing. The natural norm of this problem is the \(H^1\) norm and one has that \(\|u_h\|_{H^1} = U\cdot N U\), where \(U\) are the nodal values of the displacement field \(u_h\). The inf-sup analysis writes to disk the matrix \(N\) as well.

Consider next a mixed formulation. For example, one could analyze Stokes problem with primal variable v and dual p. The inf-sup analysis of this problem would be defined with the command

analysis, type = infsup, primal = "v", dual = "p"

The analysis will write to disk K.hwb, the global stiffness matrix. However, in this case the stiffness matrix has a block structure \(K=[A B^T; B C]\) and the three blocks will be also written to disk in the files A.hwb, B.hwb and C.hwb. Also, in addition to the natural norm for the velocities which is the \(H^1\) norm, the natural norm for the dual variables is the \(L^2\) norm. The inf-sup analysis will write to disk these two norms with the names PN.hwb and DN.hwb which correspond to the primal norm and dual norm.

A stationary analysis is one where all rate effects are ignored (this includes damping or inertial contributions). These analyses include those in which the loading is applied slowly, meaning precisely that the rate effect have a negligible effect on the solution.

In stationary analyses time must be understood as a dimensionless parameter that indicates how the solution evolves as the loading is (“slowly”) applied. The precise term for this kind of analyses is “quasistatic”

The optional commands that can be provided in a stationary analysis are:

Transient analysis are designed to solve initial boundary value problems. The equations can be of order 1 or 2 in time. The optional commands that might be given in the analysis command line are:

One should ensure that in a transient analysis the correct integrator is provided. In fact, this choise sets the order of the time derivatives as explained below.

After two or more model parts have been defined, interactions can be introduced among them. These include contact pairs, glueing parts, embedding parts, etc. interactions are entities that contribute to the energy of the system, yet have not physical “matter”. Note that they may, however, have degrees of freedom that do not belong to the interacting bodies but to the interaction itself.

The first type of interaction is used to model contact between bodies, elements, etc. It has the following syntax:

contact, penalty = <double>, type = mebody_to_plane, body = <string>,
   [, pi0 = <double>] [, pi1 = <double>] [, pi2 = <double>] [, pi3 = <double>]

contact, penalty = <double>, type = nodeset_to_plane, nodeset = <string>,
   [, pi0 = <double>] [, pi1 = <double>] [, pi2 = <double>] [, pi3 = <double>]

contact, penalty = <double>, type = nodeset_to_elset, nodeset = <string>, elset = <string>

contact, penalty = <double>, type = elset_to_elset, elset1 = <string>, elset2 = <string>

contact, penalty = <double>, type = body_to_body, body = <string>,
    body = <string> [, body = <string>, ...]

contact, penalty = <double>, type = all_bodies

contact, penalty = <double>, type = rigid_wall

A second type of interaction is use to embed one body into another one and weakly tie them. iris has interactions to embed beams, shells, and solids into solids. The advantage of these interactions is that the mesh of the embedding need not be conforming with the one of the larger body.

interaction, type = embedded_shell, solid = <string>, shell = <string>, alphashell = <double>,
             fibersubdivisions = <int>, shellthickness = <double>

interaction, type = embedded_beam, solid = <string>, beam = <string>, alphabeam = <double>,
             fibertype = <string>, fibersubdivisions = <int>, beamthickness = <double>,
             stiffness = <double>, fiberparam = <double> [, fiberparam = <double> ...],
             vect11 = <double>, vect12 = <double>, vect13 = <double>,
             vect21 = <double>, vect22 = <double>, vect23 = <double>

interaction, type = embedded_solid, solid = <string>, linked = <string>, 
             alpha = <double>, lc = <double>, stiffness = <double>

Also, thermal conductor might be embedded with the syntax

interaction, type = thbarlink, solid = <string>, bar = <string>, bar_area = <double> [, ell = <double>]

Here, a solid body is linked with a one-dimensional bar of circular cross section and area bar_area. The variable ell is used to weigh the gradient contribution in the \(H^1\) norm of the coupling. If none is given, \(\ell\) is taken to be the radius of the circular cross section. Ideally, the user should give \(\ell = (r^2\;L)^{1/3}\), where \(L\) is the length of the bar.

This interaction creates one Lagrange multiplier node at every embedded bar node to enforce the coupling. Since these multipliers belong to the interaction and not to any modelpart, initialize exposes them as named nodesets so that they can still be constrained from the input file:

• <bar>_lambda, containing every multiplier node of the interaction;
• <bar>_lambda_<vertexset>, containing the multipliers sitting on the bar nodes of the bar’s BRep vertex set <vertexset> (vertex0, vertex1, etc.), mirroring the names already used to constrain the bar’s own temperature.

This matters whenever a bar node’s temperature is prescribed: the multiplier created there has no free temperature partner, which weakens the discrete inf-sup constant of the coupling. Setting such a multiplier to zero with

bc, nodeset = <bar>_lambda_<vertexset>, variable = l, value = 0.0

removes both the unknown and its constraint row, equivalent to never having created that multiplier there, and restores the sharp inf-sup constant.

As its name indicates, nodesets and elsets are collections of nodes and elements, respectively. They enables the use of functions that operate on sets, enormously simplifying the manipulation of large sets of objects.

There are two ways to define a nodeset. First, in some low-level mesh files, nodesets are defined by providing lists of nodes. This includes the imf mesh files and also the meshes imported from Abaqus, gmsh, etc.

Second, in the .iris files one can extract sets of nodes from existing parts and give them a unique name. For example, one can create a Cartesian coordinate system and the select all nodes whose value of one or more coordinates is fixed, or whose value is within a given range (modulo some tolerance). Specifically, the nodeset selection would be obtained by issueing:

nodeset, name = <string>, modelpart = <string>, select = cartesian
   [, tolerance = <double>]
   [, centerx = <double>] [, centery = <double>] [, centerz = <double>]
   [, x = <double>] [, y = <double>] [, z = <double>]
   [, minx = <double>] [, miny = <double>] [, minz = <double>]
   [, maxx = <double>] [, maxy = <double>] [, maxz = <double>]

The default values for centerx, centery, centerz are \((0,0,0)\). Similarly, one can select nodes based on their cylindrical coordinates.

nodeset, name = <string>, modelpart = <string>, select = cylindrical
   [, tolerance = <double>]
   [, r = <double>] [, theta = <double>] [, z = <double>]
   [, centerr = <double>] [, centert = <double>] [, centerz = <double>]
   [, minr = <double>] [, mint = <double>] [, minz = <double>]
   [, maxr = <double>] [, maxt = <double>] [, maxz = <double>]

Also, one can also select the nodes on a plane with the command

nodeset, name = <string>, modelpart = <string>, select = plane
 [, tolerance = <double>]
 [, pi0 = <double>] [, pi1 = <double>] [, pi2 = <double>] [, pi3 = <double>]

Finally, one can define a nodeset directly by providing the node labels. This is not the most desirable strategy because node labels change when the mesh is refined, but can be nevertheless be useful sometimes. The syntax is:

nodeset, name = <string>, modelpart = <string>, select = labels
   [, label = <integer>] [, label = <integer>] [, label = <integer>]

Elsets are less used in IRIS at, at the moment, can only be defined in mesh files.

IRIS can create parts from (low level) mesh files containing only geometrical information of the model and following a syntax originally designed for IRIS in its first versions. The way to import such parts is using the command:

modelpart, type = mesh, filename = <string>, name = <string>, dimension = <integer>

In this type of input, the filename has node positions, elements, nodeset and elset and the maximum dimension of the modelpart is also indicated. This way of describing parts is still operational but is too poor for more advanced applications so it is being superseded by the new format, referred to as imf, or IRIS mesh format, described below.

The imf syntax has the following commands:

• nodes : this part of the file lists all the nodes in the part, giving each one a label and its coordinates.
• elements : describing groups of similar elements.

• nodeset : collecting nodes in such a way that they can be later used for boundary conditions or other needs.

  We describe next with more detail each of the parts.

IRIS has also a few importers. Each of them can take input files for other codes, such as Ansys or Abaqus, and generate an intermediate mesh file that can be later read by IRIS. In the past, the intermediate file generated by the importer had the old mesh format; in the future, these auxiliary files should adhere to the new imf syntax.

To import models from other codes IRIS still employs the command modelpart but now with the following syntax

modelpart, type = [abaqus | geo | tecplot | xml], filename = <string>,
   name = <string>, dimension = <integer>

The name is the tag employed later in the loading and boundary conditions to refer to this model. The filename is a text file with the native format of either of these codes. IRIS will process the input file, create a new imf file, and the use the latter as the input file. The dimension indicates the largest dimension of the manifold of the model part (3 for a volume, 2 for a surface, 1 for a curve), even if all nodes must be in three-dimensional space.

Before defining how boundary conditions and loads can be input into IRIS, let us introduce the concept of scaling functions and their implementation within the input file language. The code allows to introduce both of these in a way that they vary in time. For example, this would allow to shake the supports of a structure or to apply wind loads whose value and direction depend on time.

A scaling function is thus a scalar-valued function \(F\) that depends on time and space. IRIS allows to define as many as desired, even if they are never used. These functions have all additive form: they are built by simpler contributions \(f_i\) that are added before evaluation. In this way,

In IRIS, we define a scaling function by describing its elementary contributions as in

scaling, combination = <integer>,
    type = constant | gaussian | linear | sine | symbolic | tablefile | tabular | triangle 
    [,options]

Here, the combination refers to the label of the scaling function \(F\), since the individual components can not be used by themselves. Each type of scaling factor has different options as described in the table

All the scaling contributions, in addition, have two common options

The tabular scaling factor is slightly different to the rest and its syntax is:

scaling, combination = <integer>, type = tabular, [time = <double>, value = <double>]
     [, time = <double>, value = <double>]
     [, time = <double>, value = <double>] ...

With this syntax, the user can introduce pairs of time value \((t_i,v_i)\) and the tabular factor will interpolate in intermediate instants.

The tablefile uses an external file that has two columns, the first one for the time, the second one for the value of the scaling factor. Optionally, the file might have comment lines that start with the character “#”. The syntax of this scaling factor is

scaling, combination = <integer>, type = tablefile, filename = <string>

The symbolic scaling factor allows the user to define analytical expressions of the variables \((t,x,y,z,\phi,\theta,r,\rho)\) that are evaluated at every point of space and instant of time in the simulation. Here, \((x,y,z)\) are the Cartesian coordinates, \((\rho,\phi,z)\) are the cylindrical coordinates, and \((r,\phi,\theta)\) refer to the spherical coordinates. This is a very powerful command that can be used, for example, to create filters. Using the C if block syntax, one can apply loads only on certain regions of the space without the need to define new element set nor manifolds. For example, the command

scaling, combination = 1, type = symbolic, value = "x*y > 0 ? t : 0.0"

defines the scaling combination number 1 to be proportional to time in the region \(xy>0\) and zero elsewhere. The variables phi,theta,r correspond to the three spherical coordinates.

By default, IRIS creates the scaling factor with label 0, a linear factor whose value is identical to the time variable.

Boundary conditions for initial and boundary value problems are defined with the command bc. There exist severa ways to use it for reasons of backward compatibility. A major difficulty derives from the fact that IRIS now can work with multi-field problems and the name of the degree of freedom changes from problem to problem, precisely to allow combinations.

The preferable way to use bc is on manifolds. As described before, every part has manifolds defined precisely for this purpose. By using manifolds, the user does not need to know about node numbering or any other detail of the discretization but can, instead, focus on the true geometrical aspects of the model. The syntax of this version of the command is:

bc, [part | body] = <string>, setname = <string>,
    variable = <char> [, value = <double>]
    [, valuex = <double>] [, valuey = <double>] [, valuez = <double>]
    [, scaling = <integer>]

In this command, first the model part is seleted; then, the manifold is selected using the name with which each of them were defined. Then, the letter of the variable on which the boundary condition is to be applied must be given. If the varible is scalar, is suffices to give its value. If, instead, it is a vector field, then its values on the \(x,y,z\) directions can be given independently. Finally, the scaling factor can be added. If the latter is not given, it is assumed that the boundary condition is scaled by the default scaling factor (with label 0).

Boundary conditions can also be applied directly to nodesets. The syntax in this case is as follows:

bc, nodeset = <string>
   [, ux = <double>] [, uy = <double>] [, uz = <double>]
   [, p = <double>] [, e = <double>]
   [, rotx = <double>] [, roty = <double>] [, rotz = <double>]
   [, dirx = <double>] [, diry = <double>]
   [, scaling = <integer>]

This old way of applying initial conditions has an important limitation: it only works with mechanical problems in which the unknown fields have names u, p, e, are rotations or directors. It should be avoided when possible.

Initial conditions are applied on the model in a similar fashion. The syntax is

ic, [part | body] = <string>, setname = <string>,
    variable = <char> [, value = <double>]
    [, valuex = <double>] [, valuey = <double>] [, valuez = <double>]
    [, filter = <option>] [, filtertype = <option>]
    [, noise = <double>] [, noisevariance = <double>]

Alternatively, the initial condition can be given, but on a nodeset directly using

ic, nodeset = <string>,
    variable = <char> [, value = <double>]
    [, valuex = <double>] [, valuey = <double>] [, valuez = <double>]
    [, filter = <option>] [, filtertype = <option>]
    [, noise = <double>] [, noisevariance = <double>]

Finally, for second order problems, initial rates can be set using the same syntax, just modifying the keyword. Specifically, we must employ the following:

initialrate, [part | body] = <string>, setname = <string>,
    variable = <char> [, value = <double>]
    [, valuex = <double>] [, valuey = <double>] [, valuez = <double>]
    [, filter = <option>] [, filtertype = <option>]

or

initialrate, nodeset = <string>,
    variable = <char> [, value = <double>]
    [, valuex = <double>] [, valuey = <double>] [, valuez = <double>]
    [, filter = <option>] [, filtertype = <option>]

The option for the keyword filter is a symbolic expression in terms of the Cartesian coordinates \((x,y,z)\) , the cylindrical coordinates \((\rho,\phi,z)\) or the spherical ones \((r,\phi,\theta)\). The noise add a Gaussian noise on the initial condition that proportional noise, has a zero mean and variance noisevariance.

Linear multi-point constraints (MPC) allow to link the displacement degrees of freedom of different nodes with linear relations. These constraints do not reduce the number of degrees of freedom of the problem; on the contrary, each of them adds one Lagrange multiplier to the global problem, so they should be used with care.

The syntax is as follows. Given some nodes with labels \(\mathcal{L}=\{l\}\), with \(\dim(\mathcal{L})=n\), and parameters \(\{\alpha_i,\beta_i,\gamma_i \}_{i=1}^n\), the linear constraint

is imposed using the command line:

linmpc, node = l0, [, alpha = <double>] [, beta = <double>] [, gamma = <double>]
       [, node = l1, , alpha = <double>   , beta = <double>   , gamma = <double>]
       [, node = l2, , alpha = <double>   , beta = <double>   , gamma = <double>]
       [, c= <double>] [, scaling = <int>]

The scaling option allows to use a pre-defined scaling factor to multiply the constant c so that, in the constraint, \(C(t) = c\; S_i(t)\), where \(i\) is the index of the scaling function. If no scaling is provided, it is assumed that \(S_i(t)\equiv 1\).

The user is cautioned not to constrain degrees of freedom that are already constrained with the standard boundary conditions.

See example 51_Constraints/5109_linmpc.

IRIS includes some facilities to impose periodic boundary conditions, but they can only be used with prismatic blocks. To impose them, one starts by defining a model part of type brick or qbrick, as usual. Then, the following command line identifies the faces that have periodic boundary conditions

periodic, body = <string>,
     master = <string>, slave = <string>
     [, master = <string>, slave = <string>]
     [, master = <string>, slave = <string>]
     , epsxx = <double>, epsxy = <double>, epsxz = <double>
     , epsyx = <double>, epsyy = <double>, epsyz = <double>
     , epszx = <double>, epszy = <double>, epszz = <double>, \
     scaling = <int>, preconditioner = <double>

The periodic boundary conditions can be applied (on the brick surfaces) onto one, two or three face pairs. These pairs are identified by the sequence master / slave keywords. Then, at most six components of the strain operator can be defined . Finally, the scaling refers to a scaling factor that can be employed to impose gradually the deformation. If the scaling keyword is not employed, the deformation is imposed at time \(t=0\).

For other bodies, IRIS allows to impose periodic boundary conditions, although this feature should be handled with care. The user is required to define six nodesets and then use the slightly modified command:

periodic, body = <string>,
     master = <string>, slave = <string>
     [, masternodeset = <string>, slavenodeset = <string>]
     [, masternodeset = <string>, slavenodeset = <string>]
     , epsxx = <double>, epsxy = <double>, epsxz = <double>
     , epsyx = <double>, epsyy = <double>, epsyz = <double>
     , epszx = <double>, epszy = <double>, epszz = <double>, \
     scaling = <int>, preconditioner = <double>

As in the case of the master/slave surfaces, the nodesets defined above must be paired by opposing ones, and should include nodes that are exactly symmetric to each other.

The periodic boundary conditions define a Neumann problem. To make it well-posed, infinitesimal rigid body modes need to be constrained. To to so, one option is to select six degrees of freedom that are independent, and constrain them. Another option is to use the perturbed technique proposed by Kaleen and Romero. See the solid element.

The condition number of the stiffness of a mechanical problem with the periodic boundary conditions just described is not good. A remarkable improvement can be obtained if a preconditioner is employed of the order of \(E\,h\). If employed, the condition number improves significantly at the expense of the multipliers losing their physical interpretation: instead of forces, they will have dimension of length, so they need to be scaled back by \(E\,h\) to recover their physical meaning.

See example 51_Constraints/5110_periodic.

The way loads can be applied on IRIS has also evolved during the years and two methods currently co-exist. In the old, low-level, scheme, loads can be applied on nodesets, which can be selected either by their name or by the manifold that contain them. In the first case, the syntax is

loading, nodeset = <string> [,fx = <double>] [,fy = <double>] [,fz = <double>]
    [,f = <double>] [,frotx = <double>] [,froty = <double>] [,frotz = <double>]
    [,scaling = <integer>]

Here, the nodal forces \(f_x,f_y,f_z\) are conjugate to the degrees of freedom \(u_x,u_y,u_z\), while the loads \(frot_x,frot_y,frot_z\) are the moments conjugate to the rotational degrees of freedom. This command is too limited because it does not accept loads on general degrees of freedom. Alternatively, the following command can also be employed:

loading, nodeset = <string> variable = <char>] [,value = <double>]
    [,value0 = <double>] [,value1 = <double>] [,value2 = <double>]
    [,scaling = <integer>]

This latter form is more general and allows to apply loads on scalar and vector degrees of freedom, following the same syntax as the boundary conditions. Similarly, one can replace the nodeset option with the name of a model part and the manifold on which the load has to be applied. The syntax is thus

loading, [part | body] = <string>, vertex | edge | surface | volume = <integer>,
    variable = <char>] [,value = <double>]
    [,value0 = <double>] [,value1 = <double>] [,value2 = <double>]
    [,scaling = <integer>]

The previous commands apply on the nodes of the selected nodeset identical loads. This is inconsisent with variational methods where loads must be distributed according to the measure assigned to each node. For example, if a uniform load is applied to a surface, nodes on the edges and the corners should be loaded with a smaller load. To accommodate this general loading type, IRIS has a more advanced loading command with the following syntax

superloading, [part | body] = <string>, setname = <string>
    [, eltype = <int>]
    variable = <char>] [, scaling = <integer>]
    [, option = <double>] ...

In this, preferable, command, the manifold where the load has to be applied is the given by the setname on a particular body or part. The option(s) keyword(s) depends on the analysis (mechanical, thermal, fluid, etc.) as described in the appendix.

In a finite element analysis, every element has a type and a material. A model part can have elements of a single type, although it is possible to mix types. Each type must be defined with a command such as

eltype, label = <integer>, type = <keyword> [, material = <integer>] [, <command>] [, <command>] ...

The label is a unique integer label that is used, for example, in the model part definition or in the mesh files. Often the element types are linked to a material which itself is assigned to a unique label and referenced with the command material = <integer>. Element types might possess other commands that are appended to the list. Each element type is slightly different. We refer to the Appendix for the specific options of each type.

A material is defined in a similar fashion. A command line is used that gives the material a name, a label, a type, and potentially other parameters as in:

material, label = <integer>, name = <string>, type = <keyword>, [, <command>] [, <command>] ...

Depending on the analysis type, it might be the case that the solution is obtained in a step-by-step fashion. This is true for quasistatic, transient, staggered and topology optimization problems. For the solution of each step, there exist several methods where IRIS can choose from. The command line that takes care of this is:

stepsolver, type = [adr | arclength | explicit | fractional | linear | newton |
   nlcg | quasinewton]  [, <command>] [...]

The keywords correspond to the following methds

In many of the analyses that IRIS can carry out there will be, at some point, a large system of linear equations that needs to be solved. The following command selects which of the available solvers will be used for this task:

linsolver, type = [superlu | apple | hsl | pcg | ldl | wsmp | pardiso] [, <command>] [...]

In step-by-step solution, in addition to the solver, a time integration method must be provided. This is the algorithm that will take care of integrating the equations in time (for a transient problem) or in pseudo-time for a stationary problem. The command line to drive this option is

integrator, type = [quasistatic | cd | newmark | hht | midpoint] [, <command>] ...

Time stepping methods are responsible for updating the state variables after every iteration — if the step solver is nonlinear — and after the end of a time step, before starting a new one. The keywords in the command line correspond to the following methods

An important ingredient of a step-by-step is the selection of the time step size. In IRIS, this quantity can be fixed by the user, or allow the code to select it adaptatively.

tscontrol, type = [automatic | cfl | fixed] [, <command>] [...]

If a time step control is not provided, the default fixed will be employed.

IRIS generates a few files automaticall. These are

• iris.log: This is the main log file of the code. IRIS writes here all the information generated at runtime. First, IRIS writes all the information gathered from the input file (the characteristics of the analysis and the parts, the boundary conditions, the loading, materials, etc.). Then it gives information about the progress of the analysis (convergence, errors, etc.). This file is key to understand the sucdess or failure of an analysis.
• iris.warnings

Every time the code is run, it looks for the files iris.log and iris.warnings in the directory where it is being executed and deletes them if they exist. If, for any reason, the user wants to preserve the log file, IRIS should be run with the flag --save.

IRIS has the ability to dump the results obtained to files that can later be read by specialized postprocessing software. This is accomplished with the command line

postprocessor, type = [paraview | gmsh ] [, compress = <yes|no>] [, frequency = <double>]
    [smoother = <lumped|leastsquares>] [, result = <keyword>], [, result = <keyword>] [, ...],
    [,elementresult = <keyword>] [,elementresult = <keyword>] [...]

First, the user might select if the format of the postprocessing files is the one required by either Paraview or Gmsh, two programs capable of displaying graphically complex finite element solutions and related ones. The user can select as well if the output files are to be written in compressed (gzipped) format and the frequency in which the code will dump them (by default, they will be written at the end of every solution step).

The postprocessor commands writes to files the values of the degrees of freedom of them. Additionally, the user might want to obtain other results (stresses, heat fluxes, etc.) that are smoothed to the nodes or left (unsmoothed) in the elements. The commands result and elementresult serve this purpose and there can be as many as desired.

IRIS allows the user to write results obtained from the solution to text files. The syntax that needs to be employed to generate these reports is:

logger, variable = [dof | mass | reaction | bodies | stress | gradient | rate | velo | acce | energy | scaling | solution],
    settype = [element | elset | node | nodeset],
    [, nodeset = <string> | body = <string>, setname = <string>]
    [, varlabel = <integer>]
    [, filename = <string>] [, frequency = <double>]
    [, droptol = <double>] [, precision = <integer>]

The command variable selects which information should be dumped in the log file. In case the information is a degree of freedom, the variable label varlabel should be provided. The information will be extracted from a set selected using either a settype/setlabel pair or, alternatively, a named setname from a body. In the latter case the two strings should be provided.

A report will have a default name that will be replaced if a filename is provided. The data will be written to a file at every step of the solution, unless a frequency is indicated. Values smaller than droptol will be written as zero. The precission of the output can be controlled with the option that has that name.

In the case of scaling log files, they record the value in time of a given scaling combination. The syntax is as follows:

logger, variable = scaling, label = <integer>, [, filename = <string>] [, frequency = <double>]
    [, droptol = <double>] [, precision = <integer>]

and the value of the scaling combination with number label will be output to a file.

This is the scalar, linear advection–diffusion equation, for example heat or solute transport with a prescribed velocity. It uses a MUESLI conductorMaterial.

Two-node, small-strain axial bar for trusses. Its stiffness, area and mass are taken from a named bar section; no MUESLI material is used.

Geometrically exact beam for slender structural members, with translational and rotational degrees of freedom. It obtains constitutive and inertia data from a beam section.

Three-node discrete rod, useful for a bending regularisation or a simple one-dimensional bending model. It has no material.

These placeholder elements carry the corresponding point, curve, surface or volume geometry without contributing equations. They take no options.

A zero-equation link placeholder. It takes no options.

Compressible Euler/Navier–Stokes fluid element in conservative variables. It requires a MUESLI fluidMaterial.

Finite-strain axial bar for nonlinear trusses. It uses an fbar section and does not select a MUESLI material directly.

Finite-strain membrane for thin surfaces. It requires a MUESLI finiteStrainMaterial.

Nonlinear scalar Poisson/heat-conduction element. Use it when conductivity or capacity depends on the unknown; it requires MUESLI conductorMaterial.

Finite-strain rods for cables and slender members; torsionfreefrod omits the torsional mode. They use their section data rather than a MUESLI material.

Finite-strain shell elements for large-displacement thin structures. fshell uses a MUESLI finiteStrainMaterial; ftshell couples the shell to heat conduction and additionally requires a MUESLI conductorMaterial.

This element implements finite-strain mechanics in quasistatic or dynamic problems. It requires a MUESLI finiteStrainMaterial.

bbar is restricted to hexahedra. stabilized is a mixed displacement– pressure formulation; the other formulations use displacement degrees of freedom only.

Finite-strain thermomechanics, for large-deformation thermoelastic or thermoplastic solids. It requires MUESLI thermofiniteStrainMaterial.

Finite-strain thermo-chemo-mechanics. It requires MUESLI fThermoMechMassMaterial.

Finite-strain coupled thermo-mechanical mass transport. ftmc is an input alias for aotftmc. It requires MUESLI fThermoMechMassMaterial.

Finite-strain mechanics coupled with mass diffusion. fmechmass is an alias for fmm. It requires MUESLI fMechMassMaterial.

Finite-strain thermoelastic rods, the latter including electro-thermal coupling. They use their specialised structural formulation and section data.

Chemical-potential formulation for hydrogen diffusion in a solid. It requires MUESLI dissolvedHydrogenMaterial.

Lagrangian Navier–Stokes flow for moving-domain fluid problems. It requires MUESLI fluidMaterial.

Linear mass/chemical-potential diffusion. It requires MUESLI linearDiffusionMaterial.

Nonlinear scalar diffusion. It requires MUESLI nonLinearDiffusionMaterial.

Small-strain displacement–pressure solid for incompressible materials. It requires MUESLI smallStrainMaterial and is implemented for linear tetrahedra and trilinear hexahedra.

Eulerian incompressible Navier–Stokes flow. It requires MUESLI fluidMaterial.

Scalar phase-field fracture/damage equation. It does not use a MUESLI material; fracture parameters are given directly.

Coupled small-strain mechanics and phase-field fracture. It requires MUESLI smallStrainMaterial.

Kirchhoff-type plate elements for bending of thin surfaces; thermoplate adds a temperature field. They use a plate section.

Lumped point mass for discrete dynamic models. It has no MUESLI material.

Continuum linear heat conduction or a generic scalar Poisson problem. It requires MUESLI conductorMaterial.

Scalar Poisson equation with a variable transformation used to enforce bounds. It requires MUESLI conductorMaterial.

Multi-compartment reaction–diffusion/transport equation. It requires MUESLI conductorMaterial.

Concentrated rigid body with translation and rotation, for multibody dynamics.

Kinematic links. rigidlink enforces a rigid connection; trlink and rblink use either a penalty or Lagrange-multiplier constraint.

Discrete spring for linear or nonlinear connector models. It has no MUESLI material.

Three-dimensional small-strain continuum mechanics. It requires MUESLI smallStrainMaterial.

Small-strain thermomechanics (displacement and temperature). It requires MUESLI thermoElasticMaterial.

Small-strain mechanics coupled with mass transport. It requires MUESLI sMechMassMaterial.

Small-strain mechanics coupled with hydrogen diffusion. It requires MUESLI sMechMassHydMaterial.

Incompressible Stokes flow with stabilization. It requires MUESLI newtonianMaterial.

Mixed Taylor–Hood Stokes flow, with higher-order velocity than pressure. It requires MUESLI newtonianMaterial.

One-dimensional thermal network/wire with direct conductivity and storage parameters. It has no MUESLI material.

Surface reaction–diffusion element for Turing-pattern problems.

These are topology-optimization elements: macro is the mechanical macro model; the sthermoto variants add thermal design fields; svtochemp is the phase-field/Cahn–Hilliard variant. They require MUESLI smallStrainMaterial.

Lagrangian artificial-compressibility flow for incompressible Newtonian fluids. It requires MUESLI newtonianMaterial.

Heat conduction with optional laser heating and convection. It requires MUESLI conductorMaterial.

Small-strain thermomechanics with laser heating. It requires MUESLI fsThermoMechMaterial.

Frequency-domain mechanics with real and imaginary displacement fields. It requires MUESLI frequencyMaterial.

Experimental small-strain homogenization element. It requires MUESLI smallStrainMaterial.

Small-strain Timoshenko beam with selectable integration. It uses a beam section and no MUESLI material.

Two-dimensional heat-conduction layer. It requires MUESLI conductorMaterial.

This model represents the elastic, isotropic behavior for small strain mechanics.

This is the model for small strain elastoplastic behavior

Conductor materials are employed in thermal calculations. More precisely, the condutor defines a Fourier’s type relationship between heat flux and temperature gradient which is isotropic. The options are: