A core module for CREDO, since it defines and manages running models of a StGermain-based code such as Underworld.
Primary interface is via the ModelRun, which enables you to specify, configure and run a Model, and save records of this as an XML. This process will produce a credo.modelresult.ModelResult class.
Bases: dict
Small class, to record parameters that specify job control of a ModelRun, such as numbers of processors used.
All attributes are stored as regular dictionary parameters, to facilitate easy updating.
Writes information about this class into an existing, open XML doc node, in a child list
A class to keep records about a StgDomain/Underworld Model Run, including access to the underlying XML of the actual model.
This is one of the key core classes in CREDO, useful on it’s own for managing analysis, but also underlying the credo.systest module.
The basic usage pattern of this class is that a ModelRun needs to be constructed and configured to specify the basic XML files defining a StGermain Model, but also any customisations and credo.analysis.api.AnalysisOperation classes attached to be performed.
After the model is run (see credo.jobrunner), a ModelResult will be produced as a record of the run and for further analysis.
Examples of using the ModelRun are documented in CREDO, see Doing Model analysis with CREDO.
Key attributes:
name of the modelRun.
The path from which all paths to model input files (on the local machine) are specified relative to, and which the job will run in (if running on local machine).
‘Input files’ that comprise the XML model that will be run.
Output path that all model results will be saved to (is passed through to StGermain).
Path that checkpoints are read from (is passed through to StGermain).
Path that log files of the run will be saved to.
A JobParams class, to record options needed to define how the model should be actually run (eg number of procs to use).
A SimParams object, recording key parameters to control the model. This defaults to None, unless the user specifically instantiates one either in the constructor or subsequently sets this directly later. This idiom assumes that if simParams is None, all the necessary parameters are defined in the StGermain XML directly.
Note
You shouldn’t provide a particular parameter in both a SimParams object, and as an override of the ModelRun’s paramOverrides list. At both construction-time and just before the model is run, a check is performed that this has not occurred.
The name of the file storing options passed through to the PETSc numerical solver framework. Depending on the Model being solver, these can have an important role determining the performance and numerical approach taken. See the ‘System Routines’ section of PETSc 2.0.16 Changes log. This option file is separate to the paramOverrides attribute, although the options passed through to PETSc may be used to further customise matrices specified as part of StGermain components.
A file recording the options used for a modelRun will be saved in the output path, with name specified in credo.modelrun.SOLVER_OPTS_RECORD_FILENAME.
Note
the interface here has been kept as specifying a filename with the options rather than using a Python list, as the solver options can run into the hundreds, and generally several of these files are available and maintained by the developers for different solvers.
A list of StGermain XML parameter overrides that should be applied, in the form (XML_param_path, override_value). These will then be passed through at the command line.
E.g. if paramOverrides is set to [(“gravity”,0.8)], it means that the “gravity” model parameter will be set to the value 0.8.
Note
Currently this is a conceptual “catch-all” for overriding model parameters, for things not specific to the simParams list. In future this approach may be refactored.
A list of credo.analysis.api.AnalysisOperation that are associated with this ModelRun, and will be applied when the model is actually run (which involves writing and submitting additional StGermain XML).
Initally None, this will be populated with the filename of the additional XML document written containing parameter overrides, and requested analysis operations.
A list of fields that the user wishes to checkpoint in the run. Defaults to [], in which case the list (if any) in the model run’s XML will be left as-is.
Generates an XML file, in StGermainData XML format, to over-ride necessary parameters of the model as specified on this ModelRun instance. Returns the name of the just-written XML file.
Overrides can have the following main sources:
Note
Remember that as well as those overrides written to this XML, the user can over-ride particular parameters in the ModelRun via the command line by setting the self.paramOverrides member dictionary.
Check the given modelRun is valid and ready to be run.
Calculates and returns a default filename for the ModelRun’s XML record filename.
Return the full path of the executable of the modelling program. (e.g. “/usr/local/bin/StGermain”)
Given a model run, construct the command needed to run that model, and return as a string.
| Parameters: |
|
|---|
Utility function to get SimParams - since in the current design the self.simParams parameter may be ‘None’, and we need to read from the model XML.
Get the name of the file this Model’s stderr needs to/has been saved to.
Get the name of the file this Model’s stdout needs to/has been saved to.
function designed to be run after a modelRun has completed, and will do any post-run cleanup to get ready for analysis - e.g. moving files into the output directory that were created to configure the run and need to be kept.
Do any preparation necessary before the run itself proceeds.
Prepare the output and log dirs - usually in preparation for running a credo.modelrun.ModelRun.
Do any needed manipulations when setting paths.
Writes an XML recording the key details of this ModelRun, in CREDO format - useful for benchmarking etc.
writePath and filename can be specified, if not they will use default values (the outputPath of the model, and the value returned by defaultModelRunFilename(), respectively).
A class to keep records about the simulation parameters used for a StgDomain/Underworld Model Run, such as number of timesteps to run for. Has functionality to save this list to an XML record, and also read them from a StGermain XML.
After construction, it will make all these parameters directly available as attributes of the SimParams object.
A dictionary of StgParamInfo, specifying which parameters are actually controlled by this class. The keys are the short-hand names which can be used to refer to them, as well as Stgermain names.
Function to check there are no duplicates between sim param overrides set, and cmd-line parameter overrides.
Checks that the parameter set is valid to run a StGermain model (e.g. that either the stop time, or total number of steps, is set).
Get the value of a parameter with given paramName.
Utility method to get the nearest step at which a dump result was created.
Reads all the parameters of this class from a given StGermain set of input files
Writes information about this class into an existing, open XML doc node, in a child list
Writes the parameters of this class as parameters in a StGermain XML file
A simple Class that keeps track of the type of a StgParam, and it’s full name.
The name of this parameter used in the StGermain dictionary and Model XML files.
Type of this parameter (will be used in casting etc).
Default value of the parameter.
Checks that the value is of the correct type of this parameter.
Checks that, for a given list of paramOverrides, each is of a valid type that can actually be successfully used in a StGermain dictionary.
Given a tuple of desired resolutions for a model, convert this to options to pass to StG on the command line
Given a list of parameter overrides, return these as a string ready for passing to StGermain on the command line.
Turn a given tuple of resolutions into a string, suitable for using as an output dir
Writes a record, under the given parentNode, of all the parameter overrides specified in the list paramOverrides.
Writes a record, under the given parentNode, of the solver options file used.
This module allows recording and post-processing of the results of running a StGermain-based application.
The primary interface is via the ModelRun class.
See also
A class to keep records about the results of a StgDomain/Underworld model run. These are normally produced as a result of running a ModelRun.
Note
In future, we intend to add the ability to create a ModelResult class by reading in an XML file specifying output directory, etc.
Name of the Model that was run.
Path to the output results the ModelRun produced.
A jobrunner.api.JobMetaInfo, recording information about the run such as time taken, Memory usage etc (generally attached by a credo.jobrunner.api.JobRunner soon after the ModelResult created).
A list of FieldComparisonResult objects.
Note
is a legacy of early design of CREDO to allow construction of XML files from pre-existing sys test scripts, may be removed soon.
Initially None, if readFrequentOutput() is called, this will be populated with a reference to a credo.io.stgfreq.FreqOutput class, to allow post-processing of info in the Frequent Output file saved as part of the model run.
Get the default filename to use, based on the model name of a particular model.
Opens and reads in info from the Frequent Output file produced as part of the run, and saves to the attribute freqOutput.
Records the info required for a FieldResult in the array of stored FieldResults kept by the ModelResult. Returns a reference to the just-added FieldResult.
Write an XML record of a ModelResult.
utility function to get basic information about the simulation from the FrequentOutput.dat, given a particular output Path.
See also
Update an existing XML record of a ModelResult with info about a particular fieldResult.
This module allows the running of a whole suite of related ModelRun s, and managing and analysing their results as a consistent set.
The key class in this module is the ModelSuite.
For example usage, see the CREDO documentation Examples section, Examples of how to use CREDO, e.g. Using CREDO to run and analyse a Suite of Rayleigh-Taylor problems.
This class also performs a key role in the System tests provided in the credo.systest module.
Bases: credo.modelsuite.ModelVariant
A ModelVariant designed to modify job parameters.
Return the command-line string to apply this value.
Bases: exceptions.Exception
Exception for specifying that a Model Result that CREDO was asked to read in, doesn’t exist.
A class for running a suite of Models (e.g. a group for profiling, or a System Test that requires multiple runs).
The two main ways of using this class are:
The base path to use for saving model results under.
A list of ModelRun s to be run as part of the suite. See generateRuns() and addRun().
Custom sets of options (to be used at the command line) associated with each run in runs (strings).
Initially None, after the suite has been run (using runAll()), saves a reference to all ModelResult s generated.
This function will can be used to customise the model sub-path based on each modelRun. Override it if you wish to use other than the default.
(Optional) setting this to an ModelRun means this run can be used as a “template” to add variants to, and create a parameter sweep over this run.
(Related to auto-generation): A generator function to create an iterator to use when auto-generating a suite based on modelVariants. See Python module itertools module for more.
Set of StgXMLVariant s to apply to the template run in order to auto-generate a suite to vary certain parameters. See templateMRun for more.
Add a model run to the list of those to be run.
| Parameters: |
|
|---|---|
| Returns: | the index of the newly added run in the modelRun list. |
Add a StgXMLVariant to the list to be applied to a template run. See modelVariants.
Remove all stdout and stderr files from each ModelRun’s designated output and log paths.
Remove all files in each model’s output path. Useful to get rid of results still there from previous jobs. Doesn’t delete sub-directories, in case they are other model runs’ results that should be ignored.
When using a template modelRun, will generate runs for the suite based on it. The generated runs are saved to the runs attribute ready to be run using runAll().
This requires that there are one or more StgXMLVariant recorded on the class already.
| Parameters: | iterGen – this determines what iterator strategy should be used to generate the runs. Defaults to a product, but a simple “zip” style can be achieved using the itertools.izip iterator generating function. See the Python itertools module for more. |
|---|
Get the custom opts (as a string) to apply for modelRun runI.
Get a modelRun instance from the suite with a particular name.
Get the index within the suite of a run with the given name.
Convenience function to call all sub-methods for tasks to do before running to clean up directories.
Read the results generated for a given ModelSuite located off the given basePath where the suite was run, and return the list of results.
This will ignore results in the directory not related to this suite.
| Parameters: |
|
|---|
Save an XML record of each ModelResult currently in resultsList.
A class that can be added to a ModelSuite to help auto-generate a suite of ModelRuns to perform, where a particular parameter is being varied over a certain range.
This is an abstract base class, you should select an actual ModelVariant.
A list, containing the values that the parameter should be varied over. E.g. [0,1,2], or [5.6, 7.8, 9.9]. Needs to be of the correct type for the particular parameter. The Python range() function can be useful in generating such a list.
Function to apply the ii-th value of paramRange to a model.
Returns the length of the list of parameter values to vary specified in paramRange.
Return a string version of the ii-th parameter value.
Bases: credo.modelsuite.ModelVariant
A ModelVariant designed to modify StGermain XML model input parameters.
The value to use when over-riding the parameter in a StGermain dictionary, using the StGermain command line format.
E.g. Setting “gravity” would override the gravity parameter in the dictionary, whereas setting to “components.initialConditionsShape.startX” would override the startX parameter, within the initialConditionsShape component.
Return the command-line string to apply this value.
Post-processing: given a base model name and base output directory, search this directory for model results, and read into a list of ModelResult .
Note
Needs more checking added, and ability to recover metadata about the ModelRuns.
Given a varRunIsMaps generated by varRunIsMap(), a varDict and the name of another variant param in the dict, returns a mapping from the variant values to the values of the other param at the same indices.
Shortcut to create a list of param values using getParamValuesIter()
Given a list of model variants and an iterator generator function (eg itertools.izip or itertools.product) to use, generates a specific iterator that can be used on the modelVariants to obtain the actual param values.
Given a varRunIsMap generated by getVarRunIs() and an array of results, gives a mapping directly from variant values to corresponding result.
Creates a subdirectory text based on the names and values of each variant.
Simply prints the index of the run as a subdirectory.
Subdir is based on both the run index, and the textual variant names.
Generate an output sub-directory name for a run with a printed version of ModelSuite.modelVariants names, and vales for this run. (Good in the sense of being fairly self-describing, but can be long if you have many model variants).
Given a list of ModelVariants and an index iterator, returns a list of all subDirs to use.
Given a variant name, modelVariants dict and iterGen function, returns a mapping of values of the named modelVariant to run indices
Generates a list of strings to use at cmd line for each model run, given a list of StgXMLVariant and an iterator into them (e.g. generated by getVariantIndicesIter().
Given a list of model variants and iterator generator function to use, generates an iterator of indices into the modelVariants list.
Generates a list of dictionaries of parameters to be modified for each model run, given a list of StgXMLVariant and an iterator into them (e.g. generated by getVariantIndicesIter().
Generates a list of dictionaries of parameters to be modified for each model run, given a list of StgXMLVariant and an iterator into them (e.g. generated by getVariantIndicesIter().
Write a CSV file, containing all the ModelVariants defined for a ModelSuite, and also all the observables in the observablesDict.
| Parameters: |
|
|---|
Note
Could be a function on the ModelSuite?