From 4eb5a6740cd46e5017d308af22222265d152aca3 Mon Sep 17 00:00:00 2001 From: Simeon Ehrig Date: Tue, 23 Jan 2024 17:05:14 +0100 Subject: [PATCH] define naming --- README.md | 4 ++++ docs/naming.md | 17 +++++++++++++++++ 2 files changed, 21 insertions(+) create mode 100644 docs/naming.md diff --git a/README.md b/README.md index cc70800..f0f5c54 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,10 @@ This project will be the successor to the [alpaka-job-matrix-library](https://gi A library to provide a job generator for CI's for alpaka based projects. +# Naming + +The main component of the `bashi` library is combinatorics. Due to the wide spread of the field, there are different words for the same things. Therefore, `bashi` has introduced a naming guideline that is used for function and parameter names and documentation. Please read the [naming guidelines](docs/naming.md). + # 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`. diff --git a/docs/naming.md b/docs/naming.md new file mode 100644 index 0000000..2460669 --- /dev/null +++ b/docs/naming.md @@ -0,0 +1,17 @@ +# Naming + +The following guide names different components which will be used as input and output of the pair-wise generator. All components has the Python data type in brackets. + +- **parameter** (`str`): A `parameter` represents a software component like the host compiler or a specific software like `CMake` or `Boost`. A `parameter` names a list of `parameter-values` and expresses how a `parameter-value` is used. +- **parameter-value** (`Tuple[str, packaging.version.Version]`): A `parameter-value` represents of a specific version of a `parameter`, for example `GCC 10`, `nvcc 12.2` or `CMake 3.28`. +- **value-name** (`str`): The `value-name` is the first part of the `parameter-value`. It names a specific software component, like `GCC` or `CMake`. If the `parameter` names a specific software, `parameter` and `value-name` are equal. +- **value-version** (`packaging.version.Version`): The `value-version` is the second part of the `parameter-value`. It defines a specific version of a software component such like `12.2` or `3.12`. +- **parameter-value-list** (`str=List[Tuple[str, packaging.version.Version]]`): A `parameter-value-list` is a list of `parameter-values` assigned to a `parameter`. For example: + - `HOST_COMPILER=[(GCC, 10), (GCC, 11), (CLANG, 16), (CLANG, 17)]` + - `DEVICE_COMPILER=[(GCC, 10), (GCC, 11), (CLANG, 16), (CLANG, 17), (NVCC, 11.2), (NVCC, 12.0)]` + - `CMAKE=[(CMAKE, 3.22), (CMAKE, 3.23), (CMAKE, 3.24)]` +- **parameter-value-matrix** (`OrderedDict[str, List[Tuple[str, packaging.version.Version]]]`): The `parameter-value-matrix` is a list of `parameter-value-list`s. The `parameter-value-matrix` is used as input for the pair-wise generator. The data type is `OrderedDict` because the order of `parameters` is important and type of `parameter` is `str`. +- **parameter-value-tuple** (`OrderedList[Tuple[str, packaging.version.Version]]`): A `parameter-value-tuple` is a list of one ore more `parameter-value`s. The `parameter-value-tuple` is created from a ``parameter-value-matrix` and each `parameter-value` is assigned to a different `parameter`. This means, each `parameter-value` is from a different `parameter-value-list` in a `parameter-value-matrix`. The `parameter-value-tuple` has the same or a smaller number of entries as the number of `parameters` in a `parameter-value-matrix`. +- **combination** (`OrderedList[Tuple[str, packaging.version.Version]]`): A `combination` is a `parameter-value-tuple` with the same number of `parameter-value`s as the number of input `parameters`. +- **combination-list** (`List[OrderedList[Tuple[str, packaging.version.Version]]]`): A `combination-list` is a list of `combination`s an the result of the pair-wise generator. +- **parameter-value-pair** (`Tuple[Tuple[str, packaging.version.Version]], Tuple[str, packaging.version.Version]]]`): A `parameter-value-pair` is a `parameter-value-tuple` with exact two `parameter-values`. The pair-wise generator guaranties that each `parameter-value-pair`, which can be created by the given `parameter-value-matrix` exists at least in one `combination` of the `combination-list`. The only exception is, if a `parameter-value-pair` is forbidden by a filter rule.