Victor Banon Garcia / Adrien Bruneton / Teo Boutin CEA Saclay - DM2S/STMF/LGLS 03/2021

We provide here a Python package that can be used to run validation files from jupyterlab.

IMPORTANT: we assume that the methods of this module are invoked from the root directory of a validation form (i.e. a directory containing at least a 'src' subdirectory).

TRUSTCase

Class which allows the user to load and execute a validation case

Constructor: TRUSTCase(self, directory, datasetName, nbProcs=..., execOptions=..., excluNR=..., pre_run=..., post_run=...)

Initialisation of the class

Parameters:

Name	Type	Description
directory	str	Path of the file
datasetName	str	Path of the case we want to run, relatively to the 'src' folder.
nbProcs	int	Number of processors to use to run the case.
execOptions	str	TRUST Options to add at the execution of the test case
excluNR	bool	to remove of the non regression test cases

copy

copy(self, targetName, targetDirectory=..., nbProcs=..., execOptions=..., excluNR=..., pre_run=..., post_run=...)

Copy a TRUST Case. Only copies the datafile and not other optionnal atributes, such as excluNR, nbProcs, pre and post_run... These must be given again to the copy method

Parameters:

Name	Type	Description
targetName	str	New name
targetDirectory	str	New directory
nbProcs	int	number of procs
execOptions	str	TRUST Options to add at the execution of the test case
excluNR	bool	to remove of the non regression test cases

dumpDataset

dumpDataset(self, user_keywords=...)

Print out the .data file. TODO handle upper / lower case

Parameters:

Name	Type	Description
list_Trust_user_words	list(str)	List of word the user wants to color in red.

dumpDatasetMD

dumpDatasetMD(self)

Print out the .data file in a basic MarkDown format. This will not highlight TRUST keywords.

partition

partition(self, verbose=..., overwritePartition=...)

Apply partitioning of specified test case with trust -partition if nbProcs>1 only This avoids to modify trust -partition to be able to call it with 1 cpu

Parameters:

Name	Type	Description
verbose	bool
overwritePartition	bool	Whether to overwrite the partition from the dataset when running trust -partition If True, uses trust -partition xxx.data nbProcs which will overwrite (or create) the partition in the dataset, but will cut the domain in a single direction. This is the old and default behavior. If False, uses the partition from the dataset by using trust -partition xxx.data without specifying nbProcs Warning: this will not crash if there is no commented partition block in the dataset

run

run(self, verbose=...)

Execute the current test case.

In parallel mode (default):

runs the pre_run, which may also run some TRUSTCases.
if that happens, add the case to a waiting list. It will be started by TRUSTSuite.runCases() when pre_run is finished.
otherwise, directly submit the job via subprocess.Popen(...) and store it in _RUNNING_CASES.
post_run is called when the case is finished by TRUSTSuite.runCases()

In sequential mode (when preventConcurrent=True is passed to TRUSTSuite.runCases()):

runs the pre_run
wait for potential cases started by pre_run to finish
run the case and wait for it to finish
run the post_run and wait for potential cases started by post_run to finish

Sserver usage is independent of parallel/sequential mode. Jobs are submitted to SSserver if it is detected, so that preventConcurrent does not overloads cpus during complete validation

Parameters:

Name	Type	Description
verbose	bool	The results of the run are stored in members self.last_run_ok_ and self.last_run_err_

substitute

substitute(self, find, replace)

Substitute (in place and in the build directory) a part of the dataset

Parameters:

Name	Type	Description
find	str	Text we want to substitute.
replace	str	Text to insert in replacement.

substitute_template

substitute_template(self, subs_dict)

Substitute (in place and in the build directory) a part of the dataset

Parameters:

Name	Type	Description
subs_dict	dict	Text we want to substitute with python Template formalism (character identified with $ in datafile)

TRUSTSuite

A set of TRUST cases to be run for the validation form.

addCase

addCase(self, case)

No documentation.

copySrc

copySrc(self)

Copy content of src directory into build directory. WARNING: this is where we expect to be at the root of the validation form.

extractNRCases

extractNRCases(self, verbose=...)

Prints out the list of cases in a suitable format for processing by validation and lance_test tools.

verbose does nothing, just in case we forgot to remove it when actually extracting the cases (we do a complicated sed on the notebook at this step)

Teo Boutin: IMO, this shouldn't exist. concatenating the python parts of the report, doing various replacements and executing that is just a bad idea. test case extraction/lauch should be controlled by options given ro Run_fiche passed through the env var JUPYTER_RUN_OPTIONS which is parser in this file (should use argparse btw)

with args such as -get_list_cas_nr -get_nb_cas_nr -run_single_nr_case <test_name.data>

for now I will change this method to take care of executing all pre_runs of registered tests

WARNING: do not modify this without looking at scripts get_list_cas_nr and get_nb_cas_nr in Validation/Outils/Genere_Courbe/scripts

getCases

getCases(self)

No documentation.

printCases

printCases(self)

display testCases

runCases

runCases(self, verbose=..., preventConcurrent=...)

Launch all cases for the current suite.

Parameters:

Name	Type	Description
verbose	bool	whether to print the console output of the run. preventConcurrent: bool run the cases in the order they were provided, even if the Sserver is up and running, and the -parallel_sjob option was passed.

tablePerf

tablePerf(self)

Prints the table of performance

Functions

TRUST_parameters

TRUST_parameters(version=..., param=...)

Function that creates a cell Mardown giving TRUST parameters (version, binary)

Parameters:

Name	Type	Description
version	str	version of TRUST - if void TRUST_VERSION read param: list(str) List of Parameter used in this test case

addCase

addCase(directoryOrTRUSTCase, datasetName=..., nbProcs=..., execOptions=..., excluNR=..., pre_run=..., post_run=...)

Add a case to run to the list of globally recorded cases.

Parameters:

Name	Type	Description
directoryOrTRUSTCase	str	directory where the case is stored (relative to build/)
datasetName	str	Name of the case we want to run.
nbProcs	int	Number of processors
execOptions	str	TRUST Options to add at the execution of the test case
excluNR	bool	to remove of the non regression test cases

Returns: TRUSTcase instance we want to launch.

addCaseFromTemplate

addCaseFromTemplate(templateData, targetDirectory, dic, nbProcs=..., targetData=..., execOptions=..., excluNR=..., pre_run=..., post_run=...)

Add a case to run to the list of globally recorded cases.

Parameters:

Name	Type	Description
targetDirectory	str	targetDirectory where the case is stored (relative to build/) templateData: str Name of the template datafile dic: dictionary substitution of term (key identified with $ in datafile) by value in a new data file targetData : str if provided, templateData will be copied as targetData + dictionary applied + added to TRUSTSuite() nbProcs : int Number of processors excluNR : bool to remove of the non regression test cases

Returns: a new TRUSTcase instance we want to launch.

displayMD

displayMD(txt)

Display text as markdown in Jupyter notebook.

dumpDataset

dumpDataset(fiche, list_Trust_user_words=...)

Print out the .data file.

Parameters:

Name	Type	Description
fiche	str	Path of the file
list_Trust_user_words	list(str)	List of word the user wants to color in red.

dumpDatasetMD

dumpDatasetMD(data)

Print the .data file in MD format.

Parameters:

Name	Type	Description
datafile	str	relative path (to build directory) + name of datafile

dumpText

dumpText(fiche, list_keywords=...)

Print out the file.

Parameters:

Name	Type	Description
fiche	str	Path of the file

executeCommand

executeCommand(cmd, verbose=..., nonRegression=...)

Execute a bash command in the BUILD_DIRECTORY

Parameters:

Name	Type	Description
cmd	command to execute	verbose: bool nonRegression: bool

executeScript

executeScript(scriptName, verbose=..., nonRegression=...)

Execute a script shell in the BUILD_DIRECTORY

Parameters:

Name	Type	Description
scriptName	str	Name of the exec script
verbose	bool
nonRegression	bool	by default executeScript is inactive when option -not_run is applied (for non regression test)

extractNRCases

extractNRCases(verbose=...)

Prints out the list of cases in a suitable format for processing by validation and lance_test tools.

verbose does nothing, just in case we forgot to remove it when actually extracting the cases (we do a complicated sed on the notebook at this step)

WARNING: do not modify this without looking at scripts get_list_cas_nr and get_nb_cas_nr in Validation/Outils/Genere_Courbe/scripts

extraitCoupe

extraitCoupe(data_file, probe_name, time=..., verbose=..., directory=...)

execute script extrait_coupe of $TRUST_ROOT/bin

Parameters:

Name	Type	Description
directory	str	data_file: str probe_name: str verbose: bool time: value or 'all' or nothing

getCases

getCases()

No documentation.

getLastLines_

getLastLines_(err_pth)

Get last 20 lines of an error file ...

initBuildDirectory

initBuildDirectory()

triggers build directory creation and copy src stuff into it

initCaseSuite

initCaseSuite()

Instantiate a default suite of cases

introduction

introduction(auteur, creationDate=...)

Function that creates an introduction cell Mardown

Parameters:

Name	Type	Description
author	str	Name of the author of the test case. creationDate: date format dd/mm/YYYY

isExtractingNR

isExtractingNR()

Check environnement variable IS_EXTRACTING_NR to know if extracting_nr is active

isExtractingNR_ListOnly

isExtractingNR_ListOnly()

Check global variable IS_EXTRACTING_NR_LIST_ONLY to know if we want only the list of nr cases Should only be used internally. This global variable is read from os.environ at the begining (import) of this module

is_NOT_RUN

is_NOT_RUN()

Check global variable _NOT_RUN to know if option -not_run was set.

Useful if lata files are read by the user (eg. with TRUST_Post_Loader). And probably a lot of other use cases

needPrepareForNRCaseList

needPrepareForNRCaseList()

Sets IS_EXTRACTING_NR_LIST_ONLY to False.

To use when the trust runs launched manually before run.runCases are necessary in order to generate the list of non regression test cases.

printCases

printCases()

display testCases

reset

reset(keepBuildDir=..., keepSubdirectories=...)

Wipe out build directory completly and reset default suite.

runCases

runCases(verbose=..., preventConcurrent=...)

Launch all TRUST cases for the current validation form.

Parameters:

Name	Type	Description
verbose	bool	whether to print the console output of the run. preventConcurrent: bool run the cases in the order they were provided, even if the Sserver is up and running, and the -parallel_sjob option was passed.

sanitizePathToBUILD_DIRECTORY

sanitizePathToBUILD_DIRECTORY(input_path, relative=...)

Method for checking that a path given to trustutils is correctly located inside BUILD_DIRECTORY and for getting a sanitized version

Parameters:

Name	Type	Description
input_path	str	path that must be either absolute and located inside BUILD_DIRECTORY or relative (will check that it does not leave BUILD_DIRECTORY) relative: bool if False (default), path is returned as absolute if True, path is returned as relative to BUILD_DIRECTORY (for use in saveFileAccumulator mostly)

saveFileAccumulator

saveFileAccumulator(data)

Method for saving files for the Non Regression test

Parameters:

Name	Type	Description
data	str	name of the file we want to save.

saveFormOutput

saveFormOutput()

Dummy method to indicate that the output of the notebook should be saved. This method does nothing here, but its invokation is detected by the pre_save hook registered in the TRUST Jupyter configuration. By default, outputs of the validation forms are not saved.

tablePerf

tablePerf()

Prints the table of performance

useLataTools

useLataTools()

Load LataTools environment in the PYTHONPATH so that 'import TRUST_Post_Loader' can work.

useMEDCoupling

useMEDCoupling()

Load MEDCoupling environment in the PYTHONPATH so that 'import medcoupling' can work.

wait_run

wait_run(verbose=...)

Wait until all TRUST Cases have run, including cases launched from their post_run functions. This is called in TRUSTSuite methods runCases and extractNRCases.

This function waits till all cases in the global list _RUNNING_CASES are completed. post_run of such cases may append to the list, thus the need for this function.

In case of failure of a single case, it should correctly abort all others cases and display a clear error message.

Parameters:

Name	Type	Description
verbose	bool