define naming

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`.

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.