Testpackage

Usage steps

• Make a python venv.
  • Automated script testpackage/create_env.py can be used to make one, this also installs an editable analysator installation by default.
  • This additionally creates a batch script that can be sourced if the module system is used. Note that this will use the SAME python version that was used to call the script.
• Install analysator to the venv and activate it.
• Run the testpackage by running python testpackage/testpackage_commons.py [jobcount] [jobindex] [funcs].
  • For sbatch jobs see the the testpackage/run_testpackage_*.sh scripts for a starting point.

The testpackage can be made embarrassingly parallel by with setting the number of parallel jobs with jobcount and then giving each job its own jobindex to use.

The argument funcs can be used to pass the function names separated with spaces to only test certain functions. If none are given, all tests will be run.

Adding vlasiator runs to testpackage

To add a new vlasiator run to the testpackage, append a dictionary entry to the runs in testpackage/testpackage_commons.py in the following format:

runs.append( { 'name': str,                             # name of the run
                 'verifydir': str,                      # what folder output is to be placed, with format PTOUTPUTDIR/func/verifydir
                 'fileLocation': str,                   # location of datafiles
                 'fluxLocation': str or None,           # location of flux files

                 'skipped_args': dict or None,          # dictionary of function names as keys 
                                                        # and dictionary of arguments as value
                                                        # See below for more detail

                 'funcs': list,                         # list of plotting functions to test e.g plot_colormap, plot_vdf
                 'pops': list,                          # list of populations to use
                 'time': int,                           # time to use
                 'singletime': bool,                    # whether surround timesteps are available 
                 'filename': str or None,               # filename for restart file
                 'nosubpops': bool,                     # backstreaming / non-backstreaming
                 'vlasiator5': bool,                    # was the run made with vlasiator5
                 'cavitonparams': list or None          # Used for custom expressions, only required for plot_colormap
                  } )

The skipped_args dictionary can be used to leave out leave specfic arguments from a function call. The dictionary has the following format:

{function_name:{ argument_name: argument_value }}

Where:

• function_name: string, name of the function to apply the skips.
• argument_name: string, name of the named argument to skip if argument_value is in the function call.
  • can be set to 'ALL' to apply a skip to all functions.
• argument_value: string or list, if the value of the named parameter matches the argument is skipped from the call.
  • can be set to '' empty string to skip named arguments regardless of their value.

For example:

{'plot_ionosphere':{"var":["ig_z","ig_p","ig_source","ig_residual"]},'ALL':{'expression':''}}

Will change the calls in the following way:

plot_ionosphere(vlsvobj=f,var=ig_z,expression=custom_expr)  #-> plot_ionosphere(vlsvobj=f)
plot_ionosphere(vlsvobj=f,var=ig_p,expression=custom_expr)  #-> plot_ionosphere(vlsvobj=f)
plot_colormap(vlsvobj=f,expression=custom_expr)             #-> plot_plotcolormap(vlsvobj=f)

Adding new functions to the testpackage

To add new functions as tests create a file called testpackage_plot_[FUNCTION NAME].py in the folder testpackage/testpackage_definitions. In the file make lists of the function calls:

• v5restartcalls
• v5nonrestartcalls
• restartcalls
• nonrestartcalls

Look for the already defined ones for examples.

Additionally, there exists testpackage_template_maker.py which can be called with the function name to create the file. WARNING this may or may not give you something that works, thus one should go through the output and modify it as needed, this can be used as a starting point for creating tests.

Adding required arguments for functions

To refine what template maker has given, one can add required arguments to refine the calls.

In testpackage_commons.py is a dictionary of the arguments required_args that must be present for the function call to happen. The dictionary keys are function names and values are list of tuples:

"plot_isosurface":[(argument_name,default_argument)]

• argument_name: list, can contain strings or tuples, name to match the argument with, note this uses the python in operator.

  • List acts as an OR statement while tuples act as AND but only if the first argument in the tuple is present.
  • See the example below; if filedir is present then step must be present, but inverse can be true.

• default_argument: string,list or None, arguments to add if the required arguments are not present in the call. If None the call is completely skipped.

For example:

"plot_isosurface":[([("surf_step","surf_var")],["surf_step=10","surf_var='vg_rho'"]),([("filedir","step"),'vlsvobj','filename'],None)]

Adding custom expressions

The custom expressions are defined in testpackage/testpackage_custom_expr.py, see the testpackage for plot_colormap on how these are handled.