The CREDO Analysis module is to group together tools for analysis of the results of Underworld models: for use in both individual user scripts, and as part of system testing (see credo.systest).
For analysis operations that are designed to be added to ModelRun instances, and possibly used as part of system testing, these should inherit from AnalysisOperation. There are also several functions that can be used to access and post-process Underworld results in a more direct manner, using the credo.io interface.
For examples of using the analysis operations with models, see the Doing Model analysis with CREDO section of the documentation.
This is the core interface for analysis operations in CREDO.
Abstract base class for Analysis Operations in CREDO: i.e. that require some analysis to be done during a ModelRun. All instances should provide at least this standard interface so that records of analysis can be stored.
Does any required post-run actions for this analysis op, e.g. moving generated files into the correct output directory. Is passed a reference to a ModelRun, so can use it’s attributes such as outputPath.
Virtual method for writing Information XML about an analysis op, that will be saved as a record of the analysis applied.
Writes the necessary StGermain XML to require the analysis to take place. This is likely to include creating and configuring Components, and adding them to the Components dictionary. See credo.io.stgxml for the interface for setting these up.
CREDO functions and classes for doing analysis of Fields in StGermain-based codes.
Currently this is primarily based on the FieldTest component/plugin within StgFEM, which allows comparison between one or more Fields in a model run (eg “VelocityField”), and either saved reference fields, or analytic solutions.
The CREDO Field functions allow either single-model comparisons, e.g. those defined by FieldComparisonOp, or analysis on fields to be performed across multiple runs, e.g. calcFieldCvgWithScale().
Note
In future it’s planned to add functions that load a checkpointed field result into Python for further analysis, but this feature is not yet implemented.
Bases: credo.analysis.api.AnalysisOperation
Class for maintaining and managing a list of field comparisons (managed as a list of FieldComparisonOp objects), including IO from StGermain XML files.
Currently maps to the “FieldTest” component’s functionality in StgFEM.
Note
Currently the whole _list_ of Field comparisons is a single credo.analysis.api.AnalysisOperation, because this is the design of the FieldTest component in StgFEM. In future we may look at modularising this functionality further so that single comparisons can be managed as operators.
A dictionary mapping field names that need to be compared, to FieldComparisonOp to perform the comparison.
If True, means the list of fields to compare (ie fields) should be read from the Model XML files of the model to attach to. If False, the user has to manually specify the fields to compare.
Determines whether fields are compared against a reference solution (if True), or analytic (if False). If useReference is true, user must also specify referencePath so that the appropriate StGermain XML for the operation can be written.
Determines whether fields are compared against a high-res reference solution (if True), or analytic (if False). If useHighResReference is true, user must also specify referencePath so that the appropriate StGermain XML for the operation can be written.
Note
Don’t also specify useReference, choose one or the other.
(Relative or absolute) path to the reference solutions for the specified fields.
Integer, the timestep of the model that the comparison will occur at. If 0, means the final timestep. Based on the capability of the StGermain FieldTest component.
Add another FieldComparisonOp to the list to compare.
Checks that the field comparison has the writing of comparison info to file enabled (returning Bool).
Return a list of FieldComparisonResult based on all the FieldComparisonOps specified to be done during a run, from the given modelResult (ModelResult).
Returns an appropriate string to document the comparison source of the fields being compared - i.e. either reference or analytic.
Implements AnalysisOperation.postRun(). In this case, moves all CVG files created to output path.
Read in the list of fields that have already been specified to be tested from a set of StGermain input files. Useful when e.g. working with an Analytic Solution plugin.
Writes information about this class into an existing, open XML doc node, in a child element.
Writes the necessary StGermain XML to enable these specified fields to be compared.
Class for setting up and performing a comparison between two Fields. Currently uses the functionality of the FieldTest component in StgFEM, and requires using a FieldComparisonList to run a group of FieldComparisons at once (this is as a result of the structure of the FieldTest component).
name of the field that is being compared (to an analytic or ref soln).
Gets the result of the operator on the given fields (as a FieldComparisonResult), given a modelResult (ModelResult) which refers to a directory containing field comparisons (i.e. cvg files, see credo.io.stgcvg).
Writes info about a comparison op: currently assumes will be called by FieldComparisonList.writeInfoXML().
Simple class for storing CREDO FieldComparisonOp Results, so they can be analysed and saved.
By default only contains the difference between the field DOFs at the final timestep - but recording a reference to the credo.io.stgcvg.CvgFileInfo for this field allows more complex analysis.
Name of the field that has been compared.
Comparison errors for each DOF of the field, at the final timestep that was run.
A credo.io.stgcvg.CvgFileInfo allowing detailed access to the CVG result for this field. Required for plotting etc. Is optional, needs to be recorded after the class has been constructed.
If the plotOverTime() method has been called, this attribute will record the filename the plot was saved to.
Plot the result of a FieldComparison over all timesteps of a model. Requires the cvgFileInfo paramater to have been set to give access to the cvg info of this field.
Note
Requires you to have the Matplotlib library installed.
‘show’, ‘save’ and ‘path’ parameters are the same as for credo.io.stgfreq.FreqOutput.plotOverTime(). The optional ‘dofIndex’ parameter allows you to only plot a particular DOF of the field, otherwise all dofs will be plotted on separate graphs.
Checks that the difference between the fields is within a given tolerance, at the final timestep.
Writes information about a FieldComparisonResult into an existing, open XML doc node
Gets the convergence and correlation of a field with resolution (taking the log10 of both).
lenScales argument should simply be an array of length scales for the different runs. dofErrors must be a list, for each dof of the field, of the error vs some expected solution at the corresponding length scale.
returns a list of tuples, one per dof, where each tuple contains: (convergence rate, pearson correlation) over the set of scales.
Given a path that CVG files reside in, returns the length scales of each run (as a list), and a list of field error data for each field/cvg info in the given path. Thus is a utility function for generating necessary fieldErrorData for a multi-res convergence analysis.
Note
This assumes all cvg info is stored in the same convergence file (the default approach of the legacy SYS tests)
A library of useful stats functions for analysis operations.
The aim is for simple functions to be able to run without further dependencies ... with more advanced stats libraries from the likes of SciPy being able to be loaded at the user’s discretion.
Returns coefficients to the regression line “y=ax+b” from x[] and y[], and R^2 Value
(Obtained from From http://www.answermysearches.com/how-to-do-a-simple-linear-regression-in-python/124/) Useful for field analysis, e.g. when applied to a list of length scales & field errors, to calculate convergence info, such as credo.analysis.fields.calcFieldCvgWithScale().
Collection of utility functions for plotting interesting aspects of models
Calculate the number of elements used by a model run.
Create a plot of values over multiple runs.
Plot the speedup of a set of mResults, by processor.
Plot the speedup of a set of mResults, by processor.