appendices.xml

<!--
  $RCSfile: appendices.xml,v $
  $Revision: 1.3 $
  $Author: langer $
  $Date: 2011-05-02 15:47:05 $

  This software was produced by NIST, an agency of the
  U.S. government, and by statute is not subject to copyright in the
  United States.  Recipients of this software assume all
  responsibilities associated with its operation, modification and
  maintenance. However, to facilitate maintenance we ask that before
  distributing modified versions of this software, you first contact
  the authors at oof_manager@nist.gov.
-->

<appendix id="Appendix-TextMode">
  <title>Text Mode</title>
  <para>
    When &oof2; is invoked with the <link
    linkend="CommandLineArg-text"><userinput>--text</userinput></link>
    command line argument, the graphical user interface is not started
    and Python prompt
    (<quote><userinput>&gt;&gt;&gt;</userinput></quote>) is presented:
    <blockquote>
      <literallayout class="monospaced">//=*=\\=*=//=*=\\=*=//=*=\\=*=//=*=\\=*=//=*=\\=*=//=*=\\=*=//=*=\\=*=//

                          Welcome to OOF2!

OOF2 was written at the National Institute of Standards and Technology
(NIST).  NIST assumes no responsibility for the operation,
modification, or mainentance of OOF2.

//=*=\\=*=//=*=\\=*=//=*=\\=*=//=*=\\=*=//=*=\\=*=//=*=\\=*=//=*=\\=*=//

Type "OOF.Copyright()" to see the copyrights associated with OOF2.
Type "OOF.Credits()" for a list of the authors.
Type "help()" for Python help.
&gt;&gt;&gt; 
</literallayout>
    </blockquote>
    At this point, &oof2; is a normal interactive Python interpreter,
    except that all of the &oof2; modules have been imported (as well
    as the Python math module).  If you don't know Python, it's still
    possible to use text mode by reading the rest of this Appendix.
  </para>
  <para>
    &oof2;'s text mode is designed more for remote control (driving
    &oof2; from an external program) than for interactive use by a
    human being.  It <emphasis>is</emphasis> possible to use it
    interactively, but it would be a good idea to keep <xref
    linkend="Chapter-Reference"/> handy while doing so.
  </para>
  <para>
    In text mode, typing the name of an &oof2; <link
      linkend="MenuItem-OOF">command menu</link> lists the names of
    the commands and submenus that it contains.  The main menu is
    called <userinput>OOF</userinput>:
    <blockquote>
      <literallayout class="monospaced">&gt;&gt;&gt; OOF
OOF: File Windows Microstructure PixelGroup PixelSelection Credits Copyright
 Disclaimer ActiveArea Property Material NodeGroup SegmentGroup ElementGroup
 Skeleton Mesh NodeSelection SegmentSelection ElementSelection Solver Image Help
&gt;&gt;&gt;
</literallayout>
    </blockquote>
    Submenus and commands are <emphasis>members</emphasis> of their
    menus (in the OO sense), and are accessed with the Python
    <quote><userinput>.</userinput></quote> operator:
    <blockquote>
      <literallayout class="monospaced">&gt;&gt;&gt; OOF.Material
Material: New Delete Copy Add_Property Remove_Property Assign Remove
&gt;&gt;&gt;
</literallayout>
    </blockquote>
    Typing the name of a command prints nothing much useful, because a
    command doesn't have any members:
    <blockquote>
      <literallayout>&gt;&gt;&gt; OOF.Material.New
New:
&gt;&gt;&gt; 
</literallayout>
    </blockquote>
Appending parentheses to a command, however, echoes and executes it:
    <blockquote>
      <literallayout class="monospaced">&gt;&gt;&gt; OOF.Disclaimer() 
OOF.Disclaimer()

Recipients of this software assume all responsibilities associated with its
operation, modification and maintenance.
</literallayout>
    </blockquote>
    If the command requires arguments, they can be provided within the
    parentheses:
    <blockquote>
      <literallayout class="monospaced">&gt;&gt;&gt; OOF.Material.New(name='pbj')
OOF.Material.New(name='pbj')
&gt;&gt;&gt;                 
</literallayout>
    </blockquote>
    Arguments <emphasis>must</emphasis> be provided in the form
    <userinput>name=value</userinput>.  Any omitted arguments will be
    assigned the value <userinput>None</userinput>.<footnote>
      <para>
	Versions before 2.0.2 would prompt the user for missing
	arguments.  This is incompatible with the ability to have
	<emphasis>optional</emphasis> arguments, which we decided was
	more useful.
      </para>
    </footnote>
  </para>
  <para>
    All of the objects that can be used as values of command arguments
    are defined in the &oof2; Python environment.  It's therefore
    possible to type complicated commands like this:
    <blockquote>
      <literallayout class="monospaced">&gt;&gt;&gt; OOF.Skeleton.Boundary.Construct(skeleton='microstructure:skeleton',
    name='boundary',
    constructor=EdgeFromSegments(group=selection,direction='Left to right'))</literallayout>
    </blockquote>
    Consult <xref linkend="Chapter-Reference"/> for the names of the
    commands and the forms of their arguments.
  </para>
  <para>
    Some notes for those who aren't familiar with Python:
    <itemizedlist>
      <listitem>
	<para>
	  Don't type extra spaces or tabs at the beginnings of lines.
	</para>
      </listitem>
      <listitem>
	<para>
	  If you want to stretch a command over more than one line,
	  end the incomplete lines with a backslash
	  (<userinput>\</userinput>).  The backslash isn't necessary
	  if the line break is inside parentheses.
	</para>
      </listitem>
      <listitem>
	<para>
	  Character strings must be quoted. Either single or double
	  quotes may be used.
	</para>
      </listitem>
      <listitem>
	<para>
	  To exit, type <userinput>ctrl-D</userinput>, or <link
	  linkend="MenuItem-OOF.File.Quit"><userinput>OOF.File.Quit()</userinput></link>.
	</para>
      </listitem>
    </itemizedlist>
  </para>
</appendix>			<!--TextMode-->

<appendix id="Appendix-WhatsNew2.1">
  <!-- TODO: Get rid of this Appendix. First make sure that everything
       in it is covered elsewhere, if necessary. -->
  <title>What's New in &oof2; 2.1</title>
  <para>
    This appendix contains the <quote>Getting Started with OOF2
    2.1</quote> document that served as the surrogate 2.1 manual while
    the actual manual was being revised. It's being included here
    because it contains useful hints about migrating from version
    2.0.5 to 2.1.0.
  </para>
  <section id="Appendix-WhatsNew2.1-Time">
    <title>Time Dependence</title>
    <para>
      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:
      <orderedlist>
	<listitem>
	  <para>
	    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.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    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, <varname>t</varname>.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    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:
	    <itemizedlist>
	      <listitem>
		<simpara>
		  Graphics window updates.
		</simpara>
	      </listitem>
	      <listitem>
		<simpara>
		  Any quantity that can be computed on the Analysis or
		  Boundary Analysis pages.
		</simpara>
	      </listitem>
	      <listitem>
		<simpara>
		  The current state of the Mesh, saved in a file which
		  can be reloaded by OOF2.
		</simpara>
	      </listitem>
	    </itemizedlist>
	    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.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    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.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    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.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    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
	    <emphasis>static</emphasis> Solvers have been chosen, the
	    solution will be computed quasi-statically at each
	    scheduled output time.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Press the Solve button.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    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.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    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.
	  </para>
	</listitem>
      </orderedlist>
    </para>
    <para>
      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.
    </para>
  </section>			<!--Time Dependence-->
  <section id="Appendix-WhatsNew2.1-Nonlinear">
    <title>Nonlinearity</title>
    <para>
      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.
    </para>
    <para>
      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,
      <ulink
      url="http://www.ctcms.nist.gov/oof/oof2/source/OOFEXTENSIONS-1.0.0.tgz">downloadable
      separately</ulink>, contains easily modifiable examples of
      nonlinear properties.
    </para>
    <para>
      (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, <emphasis>whether or
      not</emphasis> large strain elasticity is being used.)
    </para>
    <para>
      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).
    </para>
  </section>			<!--Nonlinear-->
  <section id="Appendix-WhatsNew2.1-Behavior">
    <title>Behavioral Changes to Old Features</title>
    <section>
      <title>Rebuilding Meshes</title>
      <para>
	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
	<screen>
	  Status: Out of sync with Skeleton
	  *** Mesh must be rebuilt! ***
	</screen>
	and many Mesh operations will be prohibited until the Mesh has been
	rebuilt.
      </para>
    </section>
    <section>
      <title>Sign of Neumann Boundary Conditions</title>
      <para>
	The sign convention for Neumann boundary conditions for vector
	fluxes (<foreignphrase>i.e,</foreignphrase> heat flux or
	polarization) has been changed for consistency with the other
	fluxes.
      </para>
    </section>
    <section>
      <title>Assigning Materials to Skeleton Groups</title>
      <para>
	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 <guilabel>Element group operations</guilabel> pane in the
	Skeleton Selection page.
      </para>
    </section>
    <section>
      <title>Interface Materials</title>
      <para>
	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.
      </para>
    </section>
    <section>
      <title>No Named Profiles</title>
      <para>
	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.
      </para>
    </section>
    <section>
      <title>Periodic Boundary Conditions</title>
      <para>
	Peroidic boundary conditions are now always applied to
	<emphasis>all</emphasis> 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.
      </para>
    </section>
  </section>			<!--Behavior-->
  <section id="Appendix-WhatsNew2.1-Other">
    <title>Other New Features</title>
    <section>
      <title>Eigenvalue Outputs</title>
      <para>
	The available output quantities now include the eigenvalues of
	symmetric tensors, such as stress and strain.
      </para>
    </section>
    <section>
      <title>Output from a Skeleton Boundary</title>
      <para>
	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.
      </para>
    </section>
  </section>			<!--Other-->
  <section id="Appendix-WhatsNew2.1-GUI">
    <title>GUI Changes</title>
    <section>
      <title>Field and Equation Pages</title>
      <para>
	The old Fields and Equations pages have been merged into a
	single Fields &amp; 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.
      </para>
    </section>
    <section>
      <title>Boundary Conditions Page</title>
      <para>
	The Profile pane has been removed, because there are no named
	profiles anymore.
      </para>
      <para>
	The On/Off button has been replaced by an Enable checkbox at the
	left edge of each line in the boundary condition list.
      </para>
      <para>
	When specifying a Dirichlet boundary condition with a
	Continuum Profile, the profile function can be an explicit
	function of time, <varname>t</varname>.  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.
      </para>
    </section>
    <section>
      <title>Scheduled Output Page</title>
      <para>
	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.
      </para>
      <para>
	The page has four columns:
	<itemizedlist>
	  <listitem>
	    <para>
	      A <emphasis>checkbox</emphasis> that allows you to disable
	      a scheduled output without actually deleting it.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <emphasis>Output</emphasis>: the quantity to be
	      computed, or the action to perform.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <emphasis>Schedule</emphasis>: when to compute the
	      output.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <emphasis>Destination</emphasis>: where to send the
	      output.  For most outputs, it's either the Message
	      Window or an output stream (file).
	    </para>
	  </listitem>
	</itemizedlist>
      </para>
    </section>
    <section>
      <title>Solver Page</title>
      <para>
	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.
      </para>  
      <section>
	<title>The Solvers Pane</title>
	<para>
	  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:
	  <itemizedlist>
	    <listitem>
	      <para>
		<emphasis>Static</emphasis> isn't really a stepper.
		It just computes an equilibrium solution at the
		current time.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		<emphasis>Adaptive</emphasis> 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.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		<emphasis>Uniform</emphasis> 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.
	      </para>
	    </listitem>
	  </itemizedlist>
	</para>
	<para>
	  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.
	</para>
	<para>
	  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.
	</para>
	<para>
	  The checkbox in the column marked Solve? allows you to
	  disable the solution of a particular Subproblem.
	</para>
      </section>
      <section>
	<title>Field Initialization pane</title>
	<para>
	  The Field initialization operations have been moved from the
	  Field page to the Solver page.  Fields are initialized on
	  the whole Mesh, wherever they're defined.  The old version
	  initialized them Subproblem by Subproblem.  Also, Fields are
	  <emphasis>not</emphasis> actually initialized when their
	  initializers are set.  Values aren't changed on the Mesh
	  until the Apply or <guibutton>Apply at time</guibutton>
	  buttons are pressed.  <guibutton>Apply at time</guibutton>
	  applies the initializers after setting the Mesh's current
	  time to the given value.
	</para>
	<para>
	  If a Field initializer is set to an
	  <classname>XYTFunction</classname>, it may be a function of
	  position (<varname>x</varname> and <varname>y</varname>) or
	  time (<varname>t</varname>).  If the initializer is a
	  function of time, it does <emphasis>not</emphasis> 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.
	</para>
      </section>
      <section>
	<title>Time, Status, and Solve</title>
	<para>
	  The current time box shows the Mesh's current time.  It can
	  be changed only by reinitializing the Fields via the
	  <guibutton>Apply at time</guibutton> 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.
	</para>
	<para>
	  The Status box displays a brief message about the state of
	  the Mesh.  The Details button will display more information
	  in the message window.
	</para>
	<para>
	  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.
	</para>
      </section>
    </section>
    <section>
      <title>Analysis and Boundary Analysis Pages</title>
      <para>
	There are two changes to the Analysis and Boundary Analysis
	pages.  The first is that computations are done on the Mesh at
	a particular <emphasis>time</emphasis>.  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.
      </para>
      <para>
	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.
      </para>
    </section>
    <section>
      <title>New File Selector</title>
      <para>
	The file selector dialog has been simplified.
      </para>
    </section>
  </section>			<!--GUI-->
  <section>
    <title>Changes That May Break OOF2 Scripts</title>
    <para>
      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 <ulink url="mailto:oof_manager@nist.gov">contact
      us</ulink> if you need help updating scripts.
    </para>
    <section>
      <title>Automatically Generated PixelGroup Names</title>
      <para>
	The group names created by the Group button on the Image page,
	using <userinput>%c</userinput> as the name_template, are now
	shorter and more manageable.  OOF2 used to use its own
	representation for colors, such as
	<screen>RGBColor(red=0.24313725490196078,green=0.24313725490196078,blue=0.24313725490196078)</screen>
	Now it uses the standard hex representation,
	<computeroutput>#rrggbb</computeroutput>, where rr, gg, and bb
	are the RGB values as two digit hexadecimal numbers.  The new
	name of the above group would be
	<computeroutput>#3e3e3e</computeroutput>.
      </para>
      <para>
	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.
      </para>
    </section>
    <section>
      <title>ContinuumProfiles</title>
      <para>
	OOF2 2.0.x used the <classname>ContinuumProfile</classname>
	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.
	<itemizedlist>
	  <listitem>
	    <para>
	      Dirichlet boundary conditions require a
	      <classname>ContinuumProfileXTd</classname> object, which
	      is a time-dependent function and its first two time
	      derivatives.  Its arguments are
	      <varname>function</varname>,
	      <varname>timeDerivative</varname>, and
	      <varname>timeDerivative2</varname>, which are all
	      strings representing functions of
	      <userinput>x</userinput>, <userinput>y</userinput>,
	      <userinput>nx</userinput>, <userinput>ny</userinput>,
	      <userinput>i</userinput>, <userinput>s</userinput>,
	      <userinput>alpha</userinput>, and/or
	      <userinput>t</userinput>.  <userinput>t</userinput> is
	      time.  The rest of the variables have the same meaning
	      as in previous versions.  Here's an example:
	      <screen>
  OOF.Mesh.Boundary_Conditions.New(
      name='bc',
      mesh='microstructure:skeleton:mesh',
      condition=DirichletBC(
          field=Temperature, field_component='',
          equation=Heat_Eqn, eqn_component='',
          profile=<emphasis>ContinuumProfileXTd(function='2*t',
                                      timeDerivative='2.0',
                                      timeDerivative2='0.0')</emphasis>,
          boundary='top'))
</screen>
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      Generalized Force boundary conditions require a
	      <classname>ContinuumProfileXT</classname> object which
	      is a time-dependent function, but the time derivatives
	      do not have to be provided.  It has a
	      <varname>function</varname> argument, which is a string
	      representing a function of <userinput>x</userinput>,
	      <userinput>y</userinput>, <userinput>nx</userinput>,
	      <userinput>ny</userinput>, <userinput>i</userinput>,
	      <userinput>s</userinput>, <userinput>alpha</userinput>,
	      and/or <userinput>t</userinput>.  Example:
<screen>
  OOF.Mesh.Boundary_Conditions.Edit(
      name='bc',
      mesh='microstructure:skeleton:mesh',
      condition=ForceBC(
          equation=Heat_Eqn, eqn_component='',
          profile=<emphasis>ContinuumProfileXT(function='2*s+t')</emphasis>,
          boundary='topleft'))
  </screen>
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      Floating boundary conditions must have profile functions
	      that are not functions of time and are
	      <classname>ContinuumProfile</classname> objects.
	      <classname>ContinuumProfile</classname> objects also
	      take an argument named <varname>function</varname>, but
	      it can't be a function of <userinput>t</userinput>.
	      These are unchanged from version 2.0.
	    </para>
	  </listitem>
	</itemizedlist>
      </para>
    </section>
    <section>
      <title>Periodic Boundary Conditions</title>
      <para>
	Periodic boundary conditions now apply automatically to all
	components of a Field, so they no longer have a
	<varname>field_component</varname> argument:
<screen>
  OOF.Mesh.Boundary_Conditions.New(
      name='bc',
       mesh='microstructure:skeleton:mesh',
       condition=<emphasis>PeriodicBC(
           field=Displacement,
           equation=Force_Balance,
           boundary='right left')</emphasis>)
    </screen>
      </para>
    </section>
    <section>
      <title>Field Initialization</title>
      <para>
	The command <command>OOF.Mesh.Initialize</command> has been
	replaced by <command>OOF.Mesh.Set_Field_Initializer</command>,
	which has the same <varname>mesh</varname>,
	<varname>field</varname>, and <varname>initializer</varname>
	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
	<command>OOF.Mesh.Apply_Field_Initializers</command> or
	<command>OOF.Mesh.Apply_Field_Initializers_at_Time</command>
	<emphasis>after</emphasis> calling
	<command>OOF.Mesh.Set_Field_Initializer</command>, like this:
<screen>
  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)
 </screen>
      </para>
    </section>
    <section>
      <title>The Solve Command</title>
      <para>
	The command <command>OOF.Solver.Solve</command> has been
	replaced by the combination
	<command>OOF.Subproblem.Set_Solver</command> and
	<command>OOF.Mesh.Solve</command>.  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:
  <screen>
  OOF.Solver.Solve(
      subproblem='microstructure:skeleton:mesh:default',
      solver=LinearDriver(
          method=CGSolver(
              max_iterations=1000,
              tolerance=1e-13,
              preconditioner=ILUPreconditioner())))
  </screen>
  In 2.1, this could be replaced by
  <screen>
  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)
  </screen>
  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 <classname>CG</classname> solver to solve
  symmetric matrices and <classname>GMRES</classname> to solve
  asymmetric ones.
      </para>
    </section>
    <section>
      <title>Output Formatting</title>
      <para>
	The commands in the <command>OOF.Mesh.Analyze</command> menu
	used to take <varname>comment_character</varname> and
	<varname>separator</varname> arguments.  Those arguments have
	been replaced by global settings in the
	<guimenu>Settings/Output Formatting</guimenu> menu in the
	menubar in the main OOF2 window.  The arguments should be
	removed from scripts.
      </para>
    </section>
    <section>
      <title>Saving Images</title>
      <para>
	The <varname>mode</varname> argument to the
	<command>OOF.File.Save.Image</command> command has been
	changed to <varname>overwrite</varname>, and its value is
	either <userinput>True</userinput> or
	<userinput>False</userinput>.  Mode was either
	<userinput>write</userinput> or <userinput>append</userinput>,
	but appending to an image file doesn't make much sense.
      </para>
    </section>
  </section>			<!--Breaking Scripts-->
  <section>
    <title>Bug Fixes</title>
    <itemizedlist>
      <listitem> 
	<para>
	  The GUI test suite is much less susceptible to failures due
	  to race conditions.
	</para>
      </listitem>
      <listitem>
	<para>
	  The regression test suite no longer fails on Ubuntu systems
	  due to screen garbling.
	</para>
      </listitem>
      <listitem>
	<para>
	  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.
	</para>
      </listitem>
    </itemizedlist>
  </section>			<!--Bug Fixes-->
  <section>
    <title>Miscellany</title>
    <section>
      <title>Shouldn't it be called <quote>OOF2.1</quote>?</title>
      <para>
	You're right.  It should be <quote>OOF2.1</quote>.  But it's
	not.  OOF2 is sufficiently different from OOF, that calling it
	<quote>OOF 2</quote> seemed insufficient, so it was called
	<quote>OOF2</quote>.  But calling the first version of OOF2
	<quote>OOF2 1.0</quote> didn't seem right, so we called it
	<quote>OOF2 2.0</quote>, and are calling the new version
	<quote>OOF2 2.1</quote>.  We might call the next version
	<quote>OOF3D 3.0</quote> if we feel like it.
      </para>
    </section>
    <section>
      <title>What happened to the beta versions?</title>
      <para>
	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.
      </para>
    </section>
  </section>
</appendix>			<!--WhatsNew2.1-->

<appendix id="Appendix-Changes">
  <!-- TODO: Get rid of this Appendix. First make sure that everything
       in it is covered elsewhere, if necessary. -->
  <title>Changes to the API</title>
  <para>
    This appendix lists changes to the program that are relevant for
    people writing &oof2; extensions.
  </para>
  <section id="Appendix-Changes:2.0.2">
    <title>Changes from version 2.0.1 to 2.0.2</title>
    <itemizedlist>
      <listitem>
	<formalpara>
	  <title>Subproblem</title>
	  <para>
	    The <link
	    linkend="Class-CSubProblem"><classname>CSubProblem</classname></link>
	    class has been added.  It takes over many roles that used
	    to be filled by <link
	    linkend="Class-FEMesh"><classname>FEMesh</classname></link>.
	    Like <link
	    linkend="Class-FEMesh"><classname>FEMesh</classname></link>,
	    users should not need to use any internal methods or data
	    in the <classname>CSubProblem</classname> class. Many
	    former <classname>FEMesh</classname> function arguments
	    are now <classname>CSubProblem</classname> arguments.
	  </para>
	</formalpara>
      </listitem>
      <listitem>
	<formalpara>
	  <title>Field</title>
	  <para>
	    <itemizedlist>
	      <listitem>
		<para>
		  The <link
		  linkend="Class-FEMesh"><classname>FEMesh</classname></link>
		  arguments to <link
		  linkend="Class-Field-is_defined"><methodname>is_defined</methodname></link>
		  and <link
		  linkend="Class-Field-is_active"><methodname>is_active</methodname></link>
		  have changed to <link
		  linkend="Class-CSubProblem"><classname>CSubProblem</classname></link>.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  The <link
		  linkend="Class-Field-dofoperator"><methodname>operator()</methodname></link>,
		  <link
		  linkend="Class-Field-value"><methodname>value</methodname></link>
		  methods for extracting values at nodes no longer
		  take an <link
		  linkend="Class-FEMesh"><classname>FEMesh</classname></link>
		  argument.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  The argument to <link
		  linkend="Class-CompoundField-in_plane"><methodname>CompoundField::in_plane</methodname></link>
		  can be either a <link
		  linkend="Class-FEMesh"><classname>FEMesh</classname></link>
		  or a <link
		  linkend="Class-CSubProblem"><classname>CSubProblem</classname></link>.
		</para>
	      </listitem>
	    </itemizedlist>
	  </para>
	</formalpara>
      </listitem>
      <listitem>
	<formalpara>
	  <title>Flux</title>
	  <para>
	    The <link
	    linkend="Class-FluxData-matrix_element"><methodname>matrix_element</methodname></link>
	    and <link
	    linkend="Class-FluxData-offset_element"><methodname>offset_element</methodname></link>
	    methods in the <link
	    linkend="Class-FluxData"><classname>FluxData</classname></link>
	    class no longer take an <link
	    linkend="Class-FEMesh"><classname>FEMesh*</classname></link>
	    argument.  Their Python counterparts, <link
	    linkend="Class-FluxData-add_matrix_element"><methodname>add_matrix_element</methodname></link>
	    and <link
	    linkend="Class-FluxData-add_offset_element"><methodname>add_offset_element</methodname></link>
	    no longer take a <varname>mesh</varname> argument either.
	  </para>
	</formalpara>
      </listitem>
      <listitem>
	<formalpara>
	  <title>Property</title>
	  <para>
	    <itemizedlist>
	      <listitem>
		<para>
		  The <link
		  linkend="Class-Property"><classname>Property</classname></link>
		  member functions <link
		  linkend="Class-Property-begin_element"><methodname>begin_element</methodname></link>
		  and <link
		  linkend="Class-Property-end_element"><methodname>end_element</methodname></link>
		  now take an additional <link
		  linkend="Class-CSubProblem"><classname>CSubProblem</classname></link>
		  pointer argument.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  The first argument to the <link
		  linkend="Class-Property"><classname>Property</classname></link>
		  member functions <link
		  linkend="Class-Property-post_process"><methodname>post_process</methodname></link>,
		  <link
		  linkend="Class-Property-integration_order"><methodname>integration_order</methodname></link>,
		  and <link
		  linkend="Class-Property-is_symmetric"><methodname>is_symmetric</methodname></link>
		  is now a pointer to a <link
		  linkend="Class-CSubProblem"><classname>CSubProblem</classname></link>
		  instead of an <link
		  linkend="Class-FEMesh"><methodname>FEMesh</methodname></link>.
		</para>
	      </listitem>
	    </itemizedlist>
	  </para>
	</formalpara>
      </listitem>
      <listitem>
	<formalpara>
	  <title>Element</title>
	  <para>
	    The <link
	    linkend="Class-Element-outputField"><methodname>outputField</methodname></link>
	    and <link
	    linkend="Class-Element-outputFieldDeriv"><methodname>outputFieldDeriv</methodname></link>
	    methods in the <link
	    linkend="Class-Element"><classname>Element</classname></link>
	    class no longer take an <link
	    linkend="Class-FEMesh"><classname>FEMesh*</classname></link>
	    argument.
	  </para>
	</formalpara>
      </listitem>
      <listitem>
	<formalpara>
	  <title><classname>ElementNodeIterator</classname>, etc.</title>
	  <para>
	    The <methodname>node()</methodname> and
	    <methodname>funcnode()</methodname> functions in the <link
	    linkend="Class-ElementNodeIterator"><classname>ElementNodeIterator</classname></link>
	    classes now return a pointer to a
	    <emphasis>non-const</emphasis> <classname>Node</classname>
	    or <classname>FuncNode</classname> pointer.
	  </para>
	</formalpara>
      </listitem>
    </itemizedlist>

    
  </section>
</appendix>			<!--Changes-->

<!-- Keep this comment at the end of the file
  Local variables:
  sgml-omittag:t
  sgml-shorttag:t 
  sgml-namecase-general:nil
  sgml-minimize-attributes:nil
  sgml-always-quote-attributes:t
  sgml-indent-step:2
  sgml-indent-data:t
  sgml-parent-document:("man_oof2.xml" "book" "appendix")
  sgml-exposed-tags:nil
  sgml-local-ecat-files:nil
  End:
-->