# Getting Started with OOF2 2.1

This is a summary of the differences between OOF2 2.0.x and 2.1.0. Changes to the API for OOF2 extensions are discussed elsewhere.

## Time Dependence

You can now solve time dependent problems with OOF2. There is a tutorial in the OOF2 Help menu that walks you through a simple example. This is a summary of the steps involved:

1. Create Materials using Properties that multiply time derivative terms in the equations. For example, mass density (Mechanical:MassDensity:ConstantMassDensity) couples to the second time derivative of displacement in the force balance equation. Heat capacity (Thermal:HeatCapacity:ConstantHeatCapacity) couples to the first time derivative of temperature in the heat equation.
2. Create a Skeleton and Mesh, activate Fields and Equations, and create Boundary Conditions as before. Neumann and Dirichlet boundary conditions with continuum profiles can now depend on time, t.
3. Use the new Scheduled Output page to define outputs to be produced during the solution process. If you don't define any outputs, the computation will work, but you won't be able to measure anything at intermediate times, because the data won't be stored. Available outputs include:
• Any quantity that can be computed on the Analysis or Boundary Analysis pages.
• The current state of the Mesh, saved in a file which can be reloaded by OOF2.
For an Output to be usable, it must be given a Schedule and a Destination. The Schedule determines when the Output will be produced. It can be periodic (at fixed time intervals), geometric (at time intervals that increase by a given factor on each step), or at a given time or set of times. The Destination determines what will be done with the Output. It can be a file or the OOF2 message window. Multiple Outputs can be sent to a single file.
4. Choose a Solver, using the Solver page. A Solver must be chosen for each SubProblem that you want to solve. Solvers come in three classes: Static, Adaptive, and Uniform. Choose Static if you're not solving a time dependent problem. Adaptive Solvers adjust the time step size to maintain a given level of accuracy at the cost of some computational overhead. Uniform Solvers always use the same step size. When selecting a Solver, you can choose either Basic or Advanced mode. Basic Mode gives you fewer options and tries to make reasonable assumptions. Advanced Mode lets you make all the decisions yourself.
5. Initialize the Fields on the Mesh by creating and applying Field initializers, using the central pane on the Solve page. Initializers can be time-dependent, and can be applied at a given time. If the time is given, then it will be the starting time for subsequent calculations. If it's not given, the starting time will be the end time of the previous calculation, or 0.
6. Set the end time for the calculation, at the bottom of the Solver page. If the end time is missing or the same as the Mesh's current time (the time of the Field initialization), the problem will be solved statically at the current time. If the end time is later than the current time and non-static Solvers have been chosen, the time evolution will be computed and output produced at each scheduled time up to the end time. If the end time is later than the current time, but static Solvers have been chosen, the solution will be computed quasi-statically at each scheduled output time.
7. Press the Solve button.
8. After computing a solution, you can apply the analysis tools on the Analysis and Boundary Analysis pages at any time between the start time and the end time by using the time widget at the top of the page. The buttons on the widget will take you to the times at which output was scheduled, but you type a different time into the widget OOF2 will interpolate to that time.
9. A Mesh in a graphics window can be displayed at any scheduled output time by using the arrow buttons at the top of the plot. The time can also be adjusted using a slider or by typing a new value into the time display. The data will be interpolated if necessary. It is also possible to animate the graphics display with the Animate option in the graphics window's File menu.

Time dependent solutions can be quite large, since the values of the Fields have to be stored at every Node at every output time. OOF2 allows this data to be cached either in memory or in temporary files on disk. Caching data in memory is faster, unless you don't have enough memory. The initial cache type for new Meshes can be set via the "Settings/Mesh Defaults/Data Cache Type" command in the main OOF2 window. The cache type for an existing Mesh can be changed with the "Set Data Cache Type" option in the "Mesh Operations" pane in the FE Mesh page.

## Nonlinearity

The nonlinear solvers in OOF2 have been greatly improved in version 2.1. In Basic Solver mode, a nonlinear solver will be chosen automatically if the material properties are nonlinear. In Advanced mode, the nonlinear solver can be set to Newton, Picard, or None (indicating that a linear solver will be used). The nonlinear solvers are used to solve the finite element matrix equations both in static and time dependent problems.

The only nonlinear Material Property that is built into OOF2 is large strain elasticity (Mechanical:Elasticity:LargeStrain:Isotropic, Mechanical:Elasticity:LargeStrain:Anisotropic:Cubic, etc), which uses the rotationally invariant nonlinear strain. Other nonlinear Properties can be added. The OOFEXTENSIONS package, downloadable separately, contains easily modifiable examples of nonlinear properties.

(WARNING: Using Neumann boundary conditions expressed in normal/tangential coordinates for the force balance equation in the presence of large strains introduces nonlinearities which OOF2 does not yet handle correctly, whether or not large strain elasticity is being used.)

Nonlinear solvers are required when the Material Properties are functions of the Fields that are being solved for. OOF2 can solve nonlinearities that appear in the stiffness matrix (eg, elastic modulus, thermal conductivity) and right-hand side (eg, stress free strain, heat source) terms. It cannot solve nonlinearities that appear in a damping or mass terms (ie, multiplying the time derivatives of the Fields).

The difference between the Newton and Picard nonlinear solvers is that the Newton solver requires the derivative of the stiffness matrix with respect to the Fields. It generally converges faster than the Picard method. Newton's method works best if the nonlinear Properties compute the derivatives explicitly, but OOF2 will attempt to compute them via numerical differentiation if explicit code isn't supplied. Numerical differentiation is error-prone and slow, but may still be faster than Picard's method. (THIS IS NOT ACTUALLY CORRECT... See the 2.1 manual.)

## Behavioral Changes to Old Features

### Rebuilding Meshes

In earlier versions of OOF2, modifications to a Skeleton were automatically propagated to any Meshes based on that Skeleton. Because doing that could invalidate time step data stored on a Mesh, OOF2 no longer automatically modifies Meshes. Instead, Meshes must be explicitly updated via the Rebuild command in the Mesh Operations pane in the FE Mesh page. If a Mesh's Skeleton has been modified, the Mesh Information pane will contain

```    Status: Out of sync with Skeleton
*** Mesh must be rebuilt! ***
```
and many Mesh operations will be prohibited until the Mesh has been rebuilt.

### Sign of Neumann Boundary Conditions

The sign convention for Neumann boundary conditions for vector fluxes (i.e, heat flux or polarization) has been changed for consistency with the other fluxes.

### Assigning Materials to Skeleton Groups

Previous versions allowed Materials to be assigned to Mesh elements, overriding the Materials inherited from the Microstructure. As of 2.1, Materials can be assigned to Skeleton element groups, but not Mesh elements. Meshes inherit the Materials from their Skeletons. Materials can be assigned and removed from element groups via buttons in the “Element group operations” pane in the Skeleton Selection page.

### Interface Materials

We're still working on interfacial material properties and related issues, such as field discontinuities along internal boundaries. These were available in a rudimentary form in version 2.0.5, but were never completed, which is why 2.0.5 was always an alpha version. The interfacial properties have been removed from 2.1.0, but will return when they're ready.

### No Named Profiles

In old versions, you could give a name to a profile function that was used to define the variation of a boundary condition along the boundary. This was clumsy and overly complicated and has been removed. The only thing it was really good for was that it enabled you to use the same function in multiple boundary conditions. It's now possible to copy a boundary condition and then edit the copy, assigning it to a different boundary or different field component, which allows the profile function to be duplicated in a more natural way.

### Periodic Boundary Conditions

Peroidic boundary conditions are now always applied to all components of a Field. In old versions, you could make some Field components periodic and some aperiodic, which didn't make much sense, and made the periodicity of the out-of-plane components ambiguous. Now the out-of-plane components have the same periodicity as the other components.

## Other New Features

### Eigenvalue Outputs

The available output quantities now include the eigenvalues of symmetric tensors, such as stress and strain.

### Output from a Skeleton Boundary

In the Analysis Page, Skeleton Edge and Point boundaries can be selected as the domain for an analysis operation. The output is computed on the Mesh Elements and Nodes corresponding to the Skeleton Elements and Nodes that make up the given boundary. Because Mesh Elements can have more Nodes than the corresponding Skeleton Elements, output from Point boundaries might not include all of the points that you think it might, and might not make sense unless the boundary consists of a single Node.

## GUI Changes

### Field and Equation Pages

The old Fields and Equations pages have been merged into a single Fields & Equations page. The Field Initialization pane on the old Fields page has been moved to the Solver page. This is because the choice of a solver can determine whether or not the time derivatives of a Field need to be initialized.

### Boundary Conditions Page

The Profile pane has been removed, because there are no named profiles anymore.

The On/Off button has been replaced by an Enable checkbox at the left edge of each line in the boundary condition list.

When specifying a Dirichlet boundary condition with a Continuum Profile, the profile function can be an explicit function of time, t. The function's first and second time derivatives will have to be provided. Neumann conditions may also be functions of time, but time dependent floating boundary conditions are not allowed.

### Scheduled Output Page

This new GUI page is for defining output operations that take place during time evolution computations. If you're just solving static problems, or if you only want output at the end of the time evolution, you can skip this page entirely.

The page has four columns:

• A checkbox that allows you to disable a scheduled output without actually deleting it.
• Output: the quantity to be computed, or the action to perform.
• Schedule: when to compute the output.
• Destination: where to send the output. For most outputs, it's either the Message Window or an output stream (file).

### Solver Page

The old Solver page allowed you to solve a single Subproblem at a time. The new page lets you assign a Solver to any or all Subproblems and to solve them simultaneously.

#### The Solvers Pane

The Solvers pane lets you assign a Solver to a Subproblem. All of the defined Subproblems appear in the list. To assign a Solver, select a line in the list and use the Set button, or double click a line. You'll get a Specify Solver dialog, in which you can choose either Basic or Advanced mode. In either mode, choose a stepper:

• Static isn't really a stepper. It just computes an equilibrium solution at the current time.
• Adaptive takes time steps, with the step size adjusted to maintain a given level of accuracy. An error tolerance and minimum step size must be provided. In addition, Advanced mode requires an initial step size, an error scaling method, and a choice of algorithm for taking an error-controlled step.
• Uniform takes time steps without any step size adjustment. It may sometimes run faster than Adaptive stepping, but since there is no error control, you might not be wise to trust its answers. In many cases Uniform stepping is actually slower than Adaptive stepping, because to get an accurate answer, a Uniform stepper will have to use a small time step all of the time, whereas an Adaptive stepper will be able to use a small time step only when necessary.

In all cases, when assigning a stepper you'll have to choose whether you want the finite element matrix equations to be solved directly or iteratively. The direct solver is only suitable for small problems. Iterative matrix solvers use a lot less memory and are the better choice for most problems. In Advanced mode, you can choose the particular iterative algorithm. In Basic mode, this choice is made for you. In addition, Advanced mode lets you choose separate matrix solvers for symmetric and asymmetric matrices.

When solving a Mesh with multiple Subproblems, a single time step will be taken on each Subproblem in turn. If using an Adaptive stepper, the time step will be reduced until all Subproblems meet their error tolerances. Because one Subproblem's equations may depend on Field values from another Subproblem, each step will be repeated until each subproblem obtains a consistent result. The order in which the subproblems are addressed in this process is determined by the order in which they appear in the list in the Solvers pane. This order may be changed via the First, Earlier, Later and Last buttons at the bottom of the pane.

The checkbox in the column marked Solve? allows you to disable the solution of a particular Subproblem.

#### Field Initialization pane

The Field initialization operations have been moved from the Field page to the Solver page. Fields are initialized on the whole Mesh, whereever they're defined. The old version initialized them Subproblem by Subproblem. Also, Fields are not actually initialized when their initializers are set. Values aren't changed on the Mesh until the Apply or “Apply at time” buttons are pressed. “Apply at time” applies the initializers after setting the Mesh's current time to the given value.

If a Field initializer is set to an XYTFunction, it may be a function of position (x and y) or time (t). If the initializer is a function of time, it does not mean that the field initialized by the initializer has the given time dependence. It just means that the field's initial value is given by the value of the initializer function at the initialization time.

#### Time, Status, and Solve

The current time box shows the Mesh's current time. It can be changed only by reinitializing the Fields via the “Apply at time” button, or by solving a time dependent problem. The end time box contains the target time of a time evolution. It should be set before pressing the Solve button. If it's equal to the current time, a static solver will be used for all Subproblems even if their steppers are nonstatic.

The Status box displays a brief message about the state of the Mesh. The Details button will display more information in the message window.

The Solve button initiates a time evolution or static solution, depending on the steppers and end time. After a computation is completed, the button changes to a Continue button, and the end time is automatically incremented. If you want to continue a time evolution from where it left off, you can keep pressing the Continue button. If you make any changes to the Mesh, Skeleton, or Microstructure, the Continue button goes back to being a Solve button.

### Analysis and Boundary Analysis Pages

There are two changes to the Analysis and Boundary Analysis pages. The first is that computations are done on the Mesh at a particular time. The analysis time can be any time between the start time and the end time of the last solution. The Time widgets below the Microstructure/Skeleton/Mesh choosers are used to set the time. The buttons can be used to walk through the stored times (times at which output quantities were computed). If a time is typed into the entry box, data will be interpolated between the stored times.

The second important change is the new Named Analyses box in the bottom left corner. It lets you assign a name to the collection of settings elsewhere in the page. A named analysis may be retrieved at any time via the pull-down menu marked Current. More importantly, a named analysis may be selected as an Output in the Scheduled Output page. The only settings not included in the named analysis are the Microstructure, Skeleton, Mesh, time, and destination.

### New File Selector

The file selector dialog has been simplified.

## Changes That May Break OOF2 Scripts

Some of the changes in version 2.1.0 will require changes to OOF2 scripts that were saved by or written for version 2.0.5. Please contact us if you need help updating scripts.

### Automatically Generated PixelGroup Names

The group names created by the Group button on the Image page, using %c as the name_template, are now shorter and more manageable. OOF2 used to use its own representation for colors, such as

`RGBColor(red=0.24313725490196078,green=0.24313725490196078,blue=0.24313725490196078)`
Now it uses the standard hex representation, #rrggbb, where rr, gg, and bb are the RGB values as two digit hexadecimal numbers. The new name of the above group would be #3e3e3e.

Scripts that create pixel groups automatically and then refer to the groups explicitly by name will have to be updated with the new group names.

### ContinuumProfiles

OOF2 2.0.x used the ContinuumProfile class to specify arbitrary profile functions for boundary conditions. Now it's necessary to distinguish between constant profiles, time-dependent profiles, and time-dependent profiles that know their time derivatives. Different types of boundary conditions require different kinds of profile arguments.

• Dirichlet boundary conditions require a ContinuumProfileXTd object, which is a time-dependent function and its first two time derivatives. Its arguments are function, timeDerivative, and timeDerivative2, which are all strings representing functions of x, y, nx, ny, i, s, alpha, and/or t. t is time. The rest of the variables have the same meaning as in previous versions. Here's an example:
```  OOF.Mesh.Boundary_Conditions.New(
name='bc',
mesh='microstructure:skeleton:mesh',
condition=DirichletBC(
field=Temperature, field_component='',
equation=Heat_Eqn, eqn_component='',
profile=ContinuumProfileXTd(function='2*t',
timeDerivative='2.0',
timeDerivative2='0.0'),
boundary='top'))
```
• Generalized Force boundary conditions require a ContinuumProfileXT object which is a time-dependent function, but the time derivatives do not have to be provided. It has a function argument, which is a string representing a function of x, y, nx, ny, i, s, alpha, and/or t. Example:
```  OOF.Mesh.Boundary_Conditions.Edit(
name='bc',
mesh='microstructure:skeleton:mesh',
condition=ForceBC(
equation=Heat_Eqn, eqn_component='',
profile=ContinuumProfileXT(function='2*s+t'),
boundary='topleft'))
```
• Floating boundary conditions must have profile functions that are not functions of time and are ContinuumProfile objects. ContinuumProfile objects also take an argument named function, but it can't be a function of t. These are unchanged from version 2.0.

### Periodic Boundary Conditions

Periodic boundary conditions now apply automatically to all components of a Field, so they no longer have a field_component argument:

```  OOF.Mesh.Boundary_Conditions.New(
name='bc',
mesh='microstructure:skeleton:mesh',
condition=PeriodicBC(
field=Displacement,
equation=Force_Balance,
boundary='right left'))
```

### Field Initialization

The command OOF.Mesh.Initialize has been replaced by OOF.Mesh.Set_Field_Initializer, which has the same mesh, field, and initializer arguments as the old command. It assigns an initializer, but doesn't actually apply it. That is, it doesn't set Field values at the nodes of the Mesh. To actually set the values for all Fields, use either OOF.Mesh.Apply_Field_Initializers or OOF.Mesh.Apply_Field_Initializers_at_Time after calling OOF.Mesh.Set_Field_Initializer, like this:

```  OOF.Mesh.Set_Field_Initializer(
mesh='microstructure:skeleton:mesh',
field=Temperature, initializer=ConstScalarFieldInit(value=1.0))
OOF.Mesh.Apply_Field_Initializers(mesh='microstructure:skeleton:mesh')
OOF.Mesh.Apply_Field_Initializers_at_Time(mesh='microstructure:skeleton:mesh', time=0.0)
```

### The Solve Command

The command OOF.Solver.Solve has been replaced by the combination OOF.Subproblem.Set_Solver and OOF.Mesh.Solve. It's simplest to give an example. A typical Solve command from 2.0.5 uses a linear solver to solve the default subproblem with the CG solver:

```  OOF.Solver.Solve(
subproblem='microstructure:skeleton:mesh:default',
solver=LinearDriver(
method=CGSolver(
max_iterations=1000,
tolerance=1e-13,
preconditioner=ILUPreconditioner())))
```
In 2.1, this could be replaced by
```  OOF.Subproblem.Set_Solver(
subproblem='microstructure:skeleton:mesh:default',
solver_mode=BasicSolverMode(
time_stepper=BasicStaticDriver(),
matrix_method=BasicIterative(
tolerance=1e-13,
max_iterations=1000)))
OOF.Mesh.Solve(
mesh='microstructure:skeleton:mesh',
endtime=0.0)
```
This combination reproduces the 2.0.5 functionality and should work for any problem that 2.0.5 could solve, including nonlinear problems. It will use the CG solver to solve symmetric matrices and GMRES to solve asymmetric ones.

### Output Formatting

The commands in the OOF.Mesh.Analyze menu used to take comment_character and separator arguments. Those arguments have been replaced by global settings in the Settings/Output Formatting menu in the menubar in the main OOF2 window. The arguments should be removed from scripts.

### Saving Images

The mode argument to the OOF.File.Save.Image command has been changed to overwrite, and its value is either True or False. Mode was either write or append, but appending to an image file doesn't make much sense.

## Bug Fixes

• The GUI test suite is much less susceptible to failures due to race conditions.
• The regression test suite no longer fails on Ubuntu systems due to screen garbling.
• Saving a Mesh that had been modified, or whose Skeletons had been modified after the Mesh was created, led to a corrupt data file. It's now illegal to save a Mesh that's not synchronized with its Skeleton.

## Miscellany

### Shouldn't it be called “OOF2.1”?

You're right. It should be “OOF2.1”. But it's not. OOF2 is sufficiently different from OOF, that calling it “OOF 2” seemed insufficient, so it was called “OOF2”. But calling the first version of OOF2 “OOF2 1.0” didn't seem right, so we called it “OOF2 2.0”, and are calling the new version “OOF2 2.1”. We might call the next version “OOF3D 3.0” if we feel like it.

### What happened to the beta versions?

We're not going to release alpha or beta versions. All versions of OOF2 are tested before they're released, but we can't promise that they are bug free. When we fix bugs, we'll release a new version. When we release a new version, we'll increment the version number.