rapids_json_compute_matrix_product

Added in version v25.08.00.

Compute a matrix product from a JSON document.

rapids_json_compute_matrix_product(
  out_var
  [MATRIX_STRING <json_string>]
  [MATRIX_FILE <json_file>]
  [NO_WARN_USED]
  [NO_WARN_UNUSED]
)

This function takes a JSON document in the form of a string or a file. It returns a JSON list of flat dictionaries in the output variable based on the possible combinations of fields in the provided document. It is most commonly used to compute a matrix of nearly-identical files to be generated from a single input file with different placeholders filled in.

The algorithm is designed to be as intuitive as possible to use. It serves a similar purpose to itertools.product, but accepts arbitrarily deep hierarchies of JSON documents rather than a simple list of lists. It works as follows:

The returned value is a JSON list. Each item in the JSON list is a dictionary whose values are all primitive values (strings, booleans, numbers, and null).
Every primitive value in the input will show up in at least one matrix product entry in the output. It will be stored in the field with the same name as the dictionary field that is the most direct ancestor to the value in the input. It is an error for a primitive value to not have any dictionaries as ancestors in the input.
Each list in the input will multiply the number of matrix entries in the output by the number of items in the list. These matrix entries will contain the values within each item in the list.
Lists and dictionaries can be nested arbitrarily deep. Dictionaries can be used to group related values within a list item.

For example, consider the following JSON document:

{
  "a": [1, 2],
  "_group": [
    {
      "b": 3,
      "c": [4, 5]
    },
    {
      "b": 6,
      "c": [7, 8, 9]
    }
  ]
}

Processing this JSON document will result in the following output:

[
  {"a": 1, "b": 3, "c": 4},
  {"a": 2, "b": 3, "c": 4},
  {"a": 1, "b": 3, "c": 5},
  {"a": 2, "b": 3, "c": 5},
  {"a": 1, "b": 6, "c": 7},
  {"a": 2, "b": 6, "c": 7},
  {"a": 1, "b": 6, "c": 8},
  {"a": 2, "b": 6, "c": 8},
  {"a": 1, "b": 6, "c": 9},
  {"a": 2, "b": 6, "c": 9}
]

Notice the following details of the output:

The _group field never appears in the output. This is because it is not a direct ancestor to any primitive values and is used only for grouping.
Each c field was multiplied only with its corresponding b field. For example, "b": 3 never appears alongside "c": 7.
Recursive descent is done in alphabetical order within the dictionary. Since a comes after _group when sorted, a is iterated before _group, even though the fields within _group (b and c) come after a.

The following JSON document is an error, since it contains primitive values with no dictionary ancestors:

[1, 2]

The naming convention recommended for this algorithm is that field names that are only used for grouping and never appear in the output should start with an underscore (_), while field names that do appear in the output should not start with an underscore. Failure to follow this naming convention will not affect the proper functioning of the algorithm, but will result in a warning unless the corresponding NO_WARN_USED or NO_WARN_UNUSED argument is passed.

This function requires CMake 4.3 or newer.

out_var: Name of the variable in which to store the JSON list output.
MATRIX_STRING: String containing the JSON document to process. Mutually exclusive with the MATRIX_FILE argument.
MATRIX_FILE: File containing the JSON document to process. Mutually exclusive with the MATRIX_STRING argument.
NO_WARN_USED: Do not issue a warning if a field name that starts with an underscore appears in the output.
NO_WARN_UNUSED: Do not issue a warning if a field name that does not start with an underscore does not appear in the output.