SN_analysis.xml

<!--
  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.
-->

<section id="Section-Tasks-Analysis">
  <title>The Analysis Page</title>
  <para>
    The analysis page provides tools to examine the state of the
    physical system modelled by a given mesh.  The data can be output
    directly to a file or to the screen, for examination or plotting
    by other software, or it can be examined by one of the provided
    statistical tools.
  </para>
  <figure id="Figure-AnalysisPage">
    <title>The Analysis Page</title>
    <mediaobject>
	  <imageobject>
	    <imagedata fileref="FIGURES/gui/analysis_page.png"
                   contentwidth="880px" format="PNG"/>
	  </imageobject>
    </mediaobject>
  </figure>
  <para>
    The anatomy of the page is shown in <xref
    linkend="Figure-AnalysisPage"/>.  It begins with widgets for
    choosing which &mesh; will be the source of the data.  Below the
    &mesh; Chooser are the <link
    linkend="Section-Tasks-Analysis-Time">Time Controls</link>, which
    selects the <link linkend="Section-Concepts-Mesh-Time">time</link>
    at which the data will be extracted from the &mesh;.  The main
    part of the page consists of four panes, <link
    linkend="Section-Tasks-Analysis-OutputPane"><guilabel>Output</guilabel></link>,
    <link
    linkend="Section-Tasks-Analysis-OperationPane"><guilabel>Operation</guilabel></link>,
    <link
    linkend="Section-Tasks-Analysis-DomainPane"><guilabel>Domain</guilabel></link>,
    and <link
    linkend="Section-Tasks-Analysis-SamplingPane"><guilabel>Sampling</guilabel></link>,
    which define the analysis operation. At the bottom of the page are
    the <link linkend="Section-Tasks-Analysis-Named"><guilabel>Named
    Analysis</guilabel></link> pane, which allows analysis settings to
    be saved and restored, the <link
    linkend="Section-Tasks-Analysis-Destination"><guilabel>Destination</guilabel></link>
    pane, which determine where the results of the analysis are
    displayed or stored, and the <guilabel>Go</guilabel> button, which
    performs the analysis.
  </para>
  
  <section id="Section-Tasks-Analysis-Time">
    <title>Time Controls</title>
    <para>
      The analyses performed by this page are all computed on data
      from a particular time.  If the solution was a static solution,
      it contains only one time, and the Time Controls are
      irrelevant. If the solution was a time evolution, the Time
      Controls determine the time at which the analysis will be done.
    </para>
    <para>
	  <xref linkend="Figure-Analysis-Time"/> shows the Time Controls
	  from <xref linkend="Figure-AnalysisPage"/>.  The central box
	  displays the selected time.  A new time can be selected by
	  simply typing it into the box, or by using the buttons on either
	  side.  The buttons will only change the values to <link
	  linkend="Section-Concepts-Mesh-Time">times</link> that are
	  stored in the &mesh; (that is, the start and end times, and
	  times that were specified in <link
	  linkend="Section-Tasks-ScheduledOutput">Scheduled
	  Outputs</link>), but any time between the &mesh;'s earliest and
	  latest times can be entered into the central box.  If the box
	  contains a time that's not stored, the analysis will be based on
	  interpolated &field; values.
    </para>
    <para>
      The buttons marked <quote>Earliest</quote> and
      <quote>Latest</quote> in <xref linkend="Figure-Analysis-Time"/>
      set the time to the first and last times stored in the &mesh;.
      When these are used, the central box will read
      <userinput>&lt;earliest&gt;</userinput> or
      <userinput>&lt;latest&gt;</userinput> instead of a numerical
      time.  These placeholders always refer to the first and last
      times in the &mesh;, even if the mesh data changes.  The default
      setting for this widget is
      <userinput>&lt;latest&gt;</userinput>.
    </para>
    <figure id="Figure-Analysis-Time">
	  <title>The Time Control Widgets</title>
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref="FIGURES/gui/time_controls.png"
                     contentwidth="385px" format="PNG"/>
	    </imageobject>
	  </mediaobject>
    </figure>
  </section>

  <section id="Section-Tasks-Analysis-OutputPane">
    <title>Output Pane</title>
    <para>
	  This pane selects the output data which will be sampled on the
	  mesh.  The result is one of the available <link
	  linkend="Section-Output">output</link> types.  The buttons at
	  the top of the pane, labelled <guibutton>Scalar</guibutton> and
	  <guibutton>Aggregate</guibutton>, determine whether the
	  pull-down menus below them list the <link
	  linkend="Section-Output-Scalar">scalar outputs</link>
	  (<foreignphrase>e.g,</foreignphrase> a component of a &field; or
	  &flux;) or <link linkend="Section-Output-Aggregate">aggregate
	  outputs</link> (<foreignphrase>e.g,</foreignphrase> all of the
	  components of a &field; or &flux;).
      </para>
    </section>  
    <section id="Section-Tasks-Analysis-OperationPane">
      <title>Operation Pane</title>
      <para>
	    The operation pane determines what actually happens when the
	    <guibutton>Go</guibutton> button is pressed.  The operation is
	    one of the <xref linkend="MenuItem-OOF.Mesh.Analyze"/> menu
	    items.
      </para>
    </section>
    <section id="Section-Tasks-Analysis-DomainPane">
      <title>Domain Pane</title>
      <para>
	    The region or subset of the &mesh; on which the operation
	    should be performed is selected here.  The selection will be
	    one of the <xref linkend="RegisteredClass-Domain"/> types,
	    which define different ways of defining subregions of various
	    dimensions.
      </para>
      <para>
	    When the domain is set to <link
	    linkend="RegisteredClass-CrossSectionDomain"><guilabel>Cross
	    Section</guilabel></link>, the pane will look like <xref
	    linkend="Figure-DomainWidgets"/>.  <link
	    linkend="RegisteredClass-MeshCrossSection">Cross
	    sections</link> are lines drawn through the &micro;.  They may
	    begin and end on interior points or on edges.  Existing cross
	    sections may be selected with the chooser.  New cross sections
	    may be defined with the <link
	    linkend="MenuItem-OOF.Mesh.Cross_Section.New"><guibutton>New</guibutton></link>
	    button, which brings up a dialog box in which the coordinates
	    of the endpoints must be typed.  New cross sections can also
	    be created graphically using the <link
	    linkend="Section-Graphics-CrossSection">Mesh Cross
	    Section</link> toolbox in the <link
	    linkend="Chapter-Graphics">Graphics</link> window.
      </para>
      <para>
	    The remaining buttons in the cross section widget, <link
	    linkend="MenuItem-OOF.Mesh.Cross_Section.Copy"><guibutton>Copy</guibutton></link>,
	    <link
	    linkend="MenuItem-OOF.Mesh.Cross_Section.Edit"><guibutton>Edit</guibutton></link>,
	    <link
	    linkend="MenuItem-OOF.Mesh.Cross_Section.Rename"><guibutton>Rename</guibutton></link>,
	    and <link
	    linkend="MenuItem-OOF.Mesh.Cross_Section.Remove"><guibutton>Remove</guibutton></link>
	    do what you would expect them to do.  When a cross section is
	    removed from the chooser here, it is also removed from the
	    <link linkend="Section-Graphics-CrossSection">Mesh Cross
	    Section</link> toolbox.
      </para>
      <para>
        When the <xref linkend="RegisteredClass-Domain"/> is set to <link
        linkend="RegisteredClass-SkeletonEdgeBoundaryDomain"><guilabel>Edge
        Boundary</guilabel></link>, the boundary may lie between two
        elements, and the quantity being computed may have different
        results on different sides of the boundary.  Therefore it's
        necessary to specify which side of the boundary to use by
        setting the <varname>side</varname> parameter to
        <userinput>LEFT</userinput> or <userinput>RIGHT</userinput>,
        as shown in <xref linkend="Figure-DomainWidgets"/>.  See <xref
        linkend="Enum-SegmentSide"/> for a discussion of how
        <userinput>LEFT</userinput> and <userinput>RIGHT</userinput>
        are defined.
      </para>
      <para>
        When <xref linkend="RegisteredClass-Domain"/> is set to <link
        linkend="RegisteredClass-PixelGroup"><guilabel>Pixel
        Group</guilabel></link> or <link
        linkend="RegisteredClass-ElementGroup"><guilabel>Element
        Group</guilabel></link>, it's possible to choose a group name,
        or <userinput>&lt;selection&gt;</userinput> to set the domain
        to the currently selected pixels or &elems;.
      </para>
      <figure id="Figure-DomainWidgets">
	    <title>Two Versions of the Domain Pane</title>
	    <mediaobject>
	      <imageobject>
	        <imagedata fileref="FIGURES/gui/domainwidgets.png"
                       contentwidth="577px" format="PNG"/>
	      </imageobject>
          <caption>
            <para>
              When the domain is set to <guilabel>Cross
              Section</guilabel> the Domain Pane will look like the
              upper image.  When it's set to <guilabel>Edge
              Boundary</guilabel>, the pane will look like the lower
              image.  Other settings are simpler.
            </para>
          </caption>
	    </mediaobject>
      </figure>
    </section>


    <section id="Section-Tasks-Analysis-SamplingPane">
      <title>Sampling Pane </title> 
      <para>
	    Outputs cannot in general be evaluated directly on the
	    domains, they have to be evaluated at particular points on the
	    mesh, and depending on the desired operation, the resulting
	    pointwise data may need to be combined in some way.
      </para>
      <para>
	    The pull-down menu in the sampling pane selects a set of
	    points on which to evaluate the output, and the result is one
	    of the <xref linkend="RegisteredClass-SampleSet"/> objects.
      </para>
      <para>
	    Note that the available sample sets will depend on the current
	    settings of the <link linkend="Section-Tasks-Analysis-DomainPane"><guilabel>Domain</guilabel></link> and
	    <link linkend="Section-Tasks-Analysis-OperationPane"><guilabel>Operation</guilabel></link> panes.
      </para>
    </section>

    <section id="Section-Tasks-Analysis-Named">
      <title>Named Analyses Pane</title>
      <para>
	    The <guilabel>Named Analyses</guilabel> pane <link
	    linkend="Section-Concepts-Mesh-NamedAnalysis">assigns a
	    name</link> to the current settings of the
	    <link linkend="Section-Tasks-Analysis-OutputPane"><guilabel>Output</guilabel></link>, <link linkend="Section-Tasks-Analysis-OperationPane"><guilabel>Operation</guilabel></link>,
	    <link linkend="Section-Tasks-Analysis-DomainPane"><guilabel>Domain</guilabel></link>, and <link linkend="Section-Tasks-Analysis-SamplingPane"><guilabel>Sampling</guilabel></link>
	    panes and allows those settings to be reloaded into the panes
	    or to be used as a <link
	    linkend="Section-Concepts-Outputs-Scheduled">Scheduled
	    Output</link> during time evolution computations.
      </para>
      <para>
	    The <guilabel>Named Analysis</guilabel> pane consists of three
	    buttons labeled <guibutton>New</guibutton>,
	    <guibutton>Save</guibutton>, and <guilabel>Delete</guilabel>
	    and a pull-down menu named <guilabel>Current</guilabel>.
	    <itemizedlist>
	      <listitem>
	        <formalpara>
	          <title>New</title>
	          <para>
		        <link
		        linkend="MenuItem-OOF.Named_Analysis.Create">Create</link>
		        a new <link
		        linkend="Section-Concepts-Mesh-NamedAnalysis">Named
		        Analysis</link> using the current settings of the
		        <link linkend="Section-Tasks-Analysis-OutputPane"><guilabel>Output</guilabel></link>,
		        <link linkend="Section-Tasks-Analysis-OperationPane"><guilabel>Operation</guilabel></link>,
		        <link linkend="Section-Tasks-Analysis-DomainPane"><guilabel>Domain</guilabel></link>, and
		        <link linkend="Section-Tasks-Analysis-SamplingPane"><guilabel>Sampling</guilabel></link> panes.  A dialog box
		        will appear asking for a name, which may be generated
		        <link linkend="Object-automatic">automatically</link>.
		        Clicking <guibutton>OK</guibutton> creates the Named
		        Analysis.
	          </para>
	        </formalpara>
	        <para>
	          The new name must be unique among all Named Analyses on
	          all &meshes;, including any Named Analyses created on
	          the <link linkend="Section-Tasks-BdyAnalysis">Boundary
	          Analysis</link> page.  If the name is not unique,
	          <userinput>&lt;x&gt;</userinput> will be appended to it,
	          where <userinput>x</userinput> is an integer.
	        </para>
	      </listitem>
	      <listitem>
	        <formalpara>
	          <title>Save</title>
	          <para>
		        <link
		        linkend="MenuItem-OOF.Named_Analysis.SaveAnalysisDefs">Save</link>
		        the definitions of the Named Analyses to a file.  A
		        file chooser dialog will appear.  The
		        <guilabel>names</guilabel> list in the dialog contains
		        all of the Named Analyses.  The selected ones will be
		        saved when the <guibutton>OK</guibutton> is pressed.
		        Multiple names can be selected by shift-clicking in
		        the list.
	          </para>
	        </formalpara>
	      </listitem>
	      <listitem>
	        <formalpara>
	          <title>Delete</title>
	          <para>
		        A dialog box will appear listing all of the Named
		        Analyses.  Selecting one and clicking
		        <guibutton>OK</guibutton> will <link
		        linkend="MenuItem-OOF.Named_Analysis.Delete">delete</link>
		        it.
	          </para>
	        </formalpara>
	      </listitem>
	    </itemizedlist>
      </para>
      <para>
	    The pulldown menu labelled <guilabel>Current</guilabel>
	    displays the name of the current settings of the
	    <link linkend="Section-Tasks-Analysis-OutputPane"><guilabel>Output</guilabel></link>, <link linkend="Section-Tasks-Analysis-OperationPane"><guilabel>Operation</guilabel></link>,
	    <link linkend="Section-Tasks-Analysis-DomainPane"><guilabel>Domain</guilabel></link>, and <link linkend="Section-Tasks-Analysis-SamplingPane"><guilabel>Sampling</guilabel></link>
	    panes.  If no name has been assigned to the current
	    configuration, the menu label will be blank.  Selecting a name
	    in the menu will switch the panes to the selected
	    configuration.
      </para>
    </section>

    <section id="Section-Tasks-Analysis-Destination">
      <title>Destination Pane</title>
      <para>
	    The <guilabel>Destination</guilabel> pane determines where the
	    data generated by the analysis tool will be written.  Data can
	    appear in the <link linkend="Section-Windows-Messages">message
	    window</link>, in a previously specified file, or in a new
	    file.
      </para>
      <para>
	    The components of the pane are:
	    <itemizedlist>
	      <listitem>
	        <formalpara>
	          <title>Destination Chooser</title>
	          <para>
		        The pull-down menu at the top of the pane selects a
		        previously defined destination.  Initially, the menu
		        only contains <userinput>&lt;Message
		        Window&gt;</userinput>.
	          </para>
	        </formalpara>
	      </listitem>
	      <listitem>
	    <formalpara>
	      <title>New</title>
	      <para>
		    The <guibutton>New</guibutton> button brings up a file
		    selector dialog box.  The <varname>mode</varname>
		    parameter is a <xref linkend="Enum-WriteMode"/> and can be
		    set to <userinput>write</userinput> or
		    <userinput>append</userinput>.  If the file already
		    exists, <userinput>write</userinput> changes to
		    <userinput>OVERWRITE</userinput>, to make sure you notice.
		    Preexisting content in files opened in
		    <userinput>OVERWRITE</userinput> mode will be deleted.
	      </para>
	    </formalpara>
	    <para>
	      If the selected file has already been used for output in
	      this &oof2; session, the new data will be appended to it,
	      even if it was opened in <userinput>write</userinput> or
	      <userinput>OVERWRITE</userinput> mode, unless it has been
	      rewound.
	    </para>
	      </listitem>
	      <listitem>
	        <formalpara>
	          <title>Rewind</title>
	          <para>
		        After <link
		        linkend="MenuItem-OOF.Mesh.Analyze.Rewind">rewinding</link>
		        an output file, any new data written to the file will
		        overwrite its previous contents.  The file will
		        <emphasis>not</emphasis> be cleared until new data is
		        written.  This operation has no effect on
		        <userinput>&lt;Message Window&gt;</userinput>.
	          </para>
	        </formalpara>
	      </listitem>
	      <listitem>
	        <formalpara>
	          <title>Clear</title>
	          <para>
		        Remove all of the files from the list, except for the
		        <userinput>&lt;Message Window&gt;</userinput>.
		        Afterwards, any files opened will be treated as if
		        they're new, so data will be overwritten if they're
		        opened in <userinput>write</userinput> or
		        <userinput>OVERWRITE</userinput> mode.
	          </para>
	        </formalpara>
	      </listitem>
	    </itemizedlist>
      </para>
      <para>
	    A file opened in the <guilabel>Destination</guilabel> pane is
	    handled identically to a file opened as an <xref
	    linkend="RegisteredClass-OutputStream"/> in the <link
	    linkend="Section-Tasks-ScheduledOutput-Destination">Scheduled
	    Output</link> page.  An <xref
	    linkend="RegisteredClass-OutputStream"/> created on that page
	    will appear as a predefined destination on this page.  <link
	    linkend="Section-Tasks-ScheduledOutput-Rewind">Rewinding</link>
	    a file there has the same effect as rewinding it on this page.
      </para>
      <para>
	    The format of the output file can be adjusted by the <xref
	    linkend="MenuItem-OOF.Settings.Output_Formatting"/> menu in
	    the main &oof2; window.
      </para>
    </section>

    <section>
      <title>
        The Go Button
      </title>
      <para>
        The <guilabel>Go</guilabel> button in the bottom right corner
        of the page invokes the command in the <xref
        linkend="MenuItem-OOF.Mesh.Analyze"/> menu specified by the
        <link
        linkend="Section-Tasks-Analysis-OperationPane"><guilabel>Operation</guilabel></link>
        pane.  Data from the <link
        linkend="Section-Tasks-Analysis-OutputPane"><guilabel>Output</guilabel></link>,
        <link
        linkend="Section-Tasks-Analysis-DomainPane"><guilabel>Domain</guilabel></link>,
        <link
        linkend="Section-Tasks-Analysis-SamplingPane"><guilabel>Sampling</guilabel></link>,
        and <link linkend="Section-Tasks-Analysis-Destination"><guilabel>Destination</guilabel></link> panes are passed as
        arguments to the command.
      </para>
      <para>
        If the <guilabel>Go</guilabel> button is not sensitized,
        either some data is missing from one of the panes, the <link
        linkend="Section-Tasks-Analysis-Time">time widget</link> has
        an invalid setting, the &mesh; is <link
        linkend="RegisteredClass-RebuildMesh">out of sync</link> with
        its &skel;, or the Output is incomputable on the &mesh;.
      </para>
    </section>
  </section>    

  <!-- 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" "chapter")
  sgml-exposed-tags:nil
  sgml-local-ecat-files:nil
  End:
  -->