Advanced multiverse structures

Sometimes a multiverse is more complex than a fully connected grid of options. To express dependencies and constraints, you can add rules in the config dictionary.

Three rule types exist:

  • "exclude" — keep the universe but set specific keys to NaN when conditions match

  • "remove" — drop universes entirely when conditions match

  • "order" — control the generation order of decisions

There is also an optional flag:

  • "deduplicate" — collapse identical universes after exclude/order (defaults to True). Universes are considered identical even if their values are NaN (treated as equal).

Have a look at the following example, which would result in 36 universes for a fully connected multiverse (3 * 3 * 2 * 2). However, we decide to:

  • Exclude the value decision from all universes which contain function1 being a or b

  • Exclude the option decision from all universes with function2 being d

  • Remove all universes which contain function1 c and option False

[2]:

from comet.multiverse import Multiverse

forking_paths = {
    "function1": ["a", "b", "c"],
    "function2": ["d", "e", "f"],
    "value": [4, 5],
    "option": [True, False]
}

config = {
    "order":
        # Have universes for different ordering of functions
        [["function1", "function2", "value", "option"],
         ["function2", "function1", "value", "option"]],
    "exclude": [
        # Value is irrelevant for all function1 options
        [{"function1": "a"}, "value"],
        [{"function1": "b"}, "value"],

        # Function b never has any option → ignore it (set to NaN)
        [{"function2": "d"}, "option"],
    ],
    "remove": [
        # Function c only allowed with option == True → drop the False ones
        [{"function1": "c"}, {"option": False}],
    ],
    # Optional (True by default): make a/b/c + multiple values/options collapse cleanly
    "deduplicate": True
}

def analysis_template():
    function1 = {{function1}}
    function2 = {{function2}}
    value = {{value}}
    option = {{option}}

mverse = Multiverse(name="example_mv_structure")
mverse.create(analysis_template, forking_paths, config)
mverse.summary()

Exclusion summary
-----------------
Total number of universes: 72 (includes ordering permutations)
  - Set 'value' to NaN for universes matching {'function1': 'a'} (10 total).
  - Set 'option' to NaN for universes matching {'function2': 'd'} (8 total).
  - Set 'value' to NaN for universes matching {'function1': 'b'} (10 total).
  - Removed 8 out of 40 remaining universes:
      Rule [{'function1': 'c'}, {'option': False}] excluded 8 universes:
      {'function1': 'c', 'function2': 'e', 'value': 4, 'option': False}
      {'function1': 'c', 'function2': 'e', 'value': 5, 'option': False}
      {'function1': 'c', 'function2': 'f', 'value': 4, 'option': False}
      {'function1': 'c', 'function2': 'f', 'value': 5, 'option': False}
      {'function2': 'e', 'function1': 'c', 'value': 4, 'option': False}
      {'function2': 'e', 'function1': 'c', 'value': 5, 'option': False}
      {'function2': 'f', 'function1': 'c', 'value': 4, 'option': False}
      {'function2': 'f', 'function1': 'c', 'value': 5, 'option': False}

32 universes remain for analysis.
Universe Decision 1 Value 1 Decision 2 Value 2 Decision 3 Value 3 Decision 4 Value 4
0 Universe_1 function1 a function2 d value NaN option NaN
1 Universe_2 function1 a function2 e value NaN option True
2 Universe_3 function1 a function2 e value NaN option False
3 Universe_4 function1 a function2 f value NaN option True
4 Universe_5 function1 a function2 f value NaN option False
5 Universe_6 function1 b function2 d value NaN option NaN
6 Universe_7 function1 b function2 e value NaN option True
7 Universe_8 function1 b function2 e value NaN option False
8 Universe_9 function1 b function2 f value NaN option True
9 Universe_10 function1 b function2 f value NaN option False
10 Universe_11 function1 c function2 d value 4.0 option NaN
11 Universe_12 function1 c function2 d value 5.0 option NaN
12 Universe_13 function1 c function2 e value 4.0 option True
13 Universe_14 function1 c function2 e value 5.0 option True
14 Universe_15 function1 c function2 f value 4.0 option True
15 Universe_16 function1 c function2 f value 5.0 option True
16 Universe_17 function2 d function1 a value NaN option NaN
17 Universe_18 function2 d function1 b value NaN option NaN
18 Universe_19 function2 d function1 c value 4.0 option NaN
19 Universe_20 function2 d function1 c value 5.0 option NaN
20 Universe_21 function2 e function1 a value NaN option True
21 Universe_22 function2 e function1 a value NaN option False
22 Universe_23 function2 e function1 b value NaN option True
23 Universe_24 function2 e function1 b value NaN option False
24 Universe_25 function2 e function1 c value 4.0 option True
25 Universe_26 function2 e function1 c value 5.0 option True
26 Universe_27 function2 f function1 a value NaN option True
27 Universe_28 function2 f function1 a value NaN option False
28 Universe_29 function2 f function1 b value NaN option True
29 Universe_30 function2 f function1 b value NaN option False
30 Universe_31 function2 f function1 c value 4.0 option True
31 Universe_32 function2 f function1 c value 5.0 option True