alpaka-job-matrix-library
A library to provide a job generator for CI's for alpaka based projects.
The library provides everything needed to generate a sparse combination matrix for alpaca-based projects, including a set of general-purpose combination rules.
The provision of the input parameters, the reordering of the jobs, the filtering of the job matrix and the generation of the job yaml are project specific. Therefore, the library provides an example of how most parts can be implemented.
Installation
Install via pip:
pip install alpaka-job-coverage
See pypi.org
Usage
The main function of the library is create_job_list()
. It takes a list of parameters, creates the combinations, applies the combination rules, thins them and returns the sparse job matrix.
The thinning is done according to the principle all-pairs testing. The principle means that every combination of the values of at least two parameters must be part of a job, unless a filter rule forbids this. The pair_size
parameter of the create_job_list()
function decides how large the combination tuple must be. For example, if we have the parameter fields A, B, C
and D
and pair size 2, each combination of the values of AB, AC, AD, BC, BD and CD
must be part of a job. If the parameter is 3, any combination of the values of ABC, ABD and BCD
must be part of a job. Normally, a larger pairwise factor increases the calculation time and the number of orders.
The general form of the parameter matrix is an OrderedDict
of List[Tuples[str, str]]
. The first value of a tuple is the name of the software and the second value is the version. An exception is the parameter field BACKENDS
. BACKENDS
is a list[list[tuple[str, str]]
. The inner list contains a combination of alpaka backends. This can be a complete combination matrix of all backends (the inner list contains n entries), or it can be only one backend (size of the inner list is 1), as required for cupla. A mixture of both is also possible, e.g. [(ALPAKA_ACC_CPU_B_SEQ_T_SEQ_ENABLE, ON), (ALPAKA_ACC_CPU_B_OMP2_T_SEQ_ENABLE, ON), (ALPAKA_ACC_CPU_B_SEQ_T_OMP2_ENABLE, ON)],[(ALPAKA_ACC_GPU_CUDA_ENABLE, "11. 0")],[(ALPAKA_ACC_GPU_CUDA_ENABLE, "11.0")] ...]
.
In order to apply the filter rules correctly, it is necessary to use the variables defined in alpaka_job_coverage.global
.
There are 3 parameters with special meaning:
HOST_COMPILER
: Compiler for the host code, or if there is no host device code separation, the compiler for all the code.DEVICE_COMPILER
: Compiler for the device code, or if there is no host device code separation, the compiler is the same as the host compiler.BACKENDS
: See description above.
If one of these 3 parameter fields is missing, it is not guaranteed that the generator will provide correct results. All other parameter fields provided by the alpaka_job_coverage.global
are optional.
Adding own parameter and rules
If you want to use a project-specific parameter, you can simply add it to the parameter list and the library will apply it. To limit the possible combinations of your new parameter, you need to add a new filter function. The create_job_list()
function applies a chain of filter functions to each possible combination. Before and after each filter function is a function hook where you can insert your own filter function. The order is described in the doc string of create_job_list()
. When you create a new filter rule, you must comply with the following rules:
- The filter returns
True
if a combination is valid andFalse
if not. All filters in the library follow the rule that every combination is valid until it is forbidden (blacklist). - The input of the filter is a combination of the values of the individual parameter fields, and the combination does not have to be complete. The list can contain at least 2 parameter fields up to all. You must check whether a parameter field is included in the current combination.
- If a parameter field is not included in the current combination, it means that it can contain any possible value of this parameter. In practice, this means that if you only check for the presence of the parameter and return
False
, if the parameter is not present, no combination is possible.
ajc-validate
ajc-validate
is a tool which is installed together with the alpaka-job-coverage
library. The tool allows to check whether a combination of parameters passes the different filters and displays the reason if not.
Hint: The source code of the tool is located in the file validate.py.
Developing
It is strongly recommended to use a Python environment for developing the code, such as virtualenv
or a conda
environment. The following code uses a virtualenv
.
- Create the environment:
virtualenv -p python3 env
- Activate the environment:
source env/bin/activate
- Install the library:
python setup.py develop
- Test the installation with the example:
python3 example/example.py 3.0
- You can run the unit tests by going to the
test
directory and runningpython -m unittest
If the example works correctly, a job.yml
will be created in the current directory. You can also run python3 example/example.py --help
to see additional options.
Now the library is available in the environment. Therefore you can easily use the library in your own projects via import alpaka_job_coverage as ajc
.
Formatting the source code
The source code is formatted using the black formatter and the default style guide. You must install it and run black /path/to/file
to format a file. A CI job checks that all files are formatted correctly. If the job fails, a PR cannot be merged.
Contribution
This section contains some hints for developing new functions. The hints are mainly for people who have no experience with setuptools
and building pip
packages.
- The
python setup.py develop
command installs the source code files as a symbolic link. This means that changes in the source code of the Python files in thesrc/alpaka_job_coverage
folder are directly available without any additional installation step (only a restart of the Python process/interpreter is required). - The software requirements are defined in
setup.py
and not in an additionalrequirements.txt
. - It is necessary to increase the version number in
version.txt
before a new feature can be merged in the master branch. Otherwise the upload to pypy.org will fail because existing versions cannot be changed.