Add default generators (#431)

bofire/utils/default_fracfac_generators.py

@@ -0,0 +1,170 @@
+import pandas as pd
+
+# this are the default generators used for fractional factorial designs in BoFire
+default_fracfac_generators = pd.DataFrame.from_dict(
+ [
+ {"n_factors": 3, "n_generators": 1, "generator": "C = AB"},
+ {"n_factors": 4, "n_generators": 1, "generator": "D = ABC"},
+ {"n_factors": 5, "n_generators": 1, "generator": "E = ABCD"},
+ {"n_factors": 5, "n_generators": 2, "generator": "D= AB ; E= AC"},
+ {"n_factors": 6, "n_generators": 1, "generator": "F = ABCDE"},
+ {"n_factors": 6, "n_generators": 2, "generator": "E = ABC ; F = BCD"},
+ {"n_factors": 6, "n_generators": 3, "generator": "D= AB ; E= AC ; F= BC"},
+ {"n_factors": 7, "n_generators": 1, "generator": "G = ABCDEF"},
+ {"n_factors": 7, "n_generators": 2, "generator": "F = ABCD ; G = ABDE"},
+ {"n_factors": 7, "n_generators": 3, "generator": "F = ABC ; F = BCD ; G = ACD"},
+ {
+ "n_factors": 7,
+ "n_generators": 4,
+ "generator": "D = AB ; E= AC ; F = BC ; G = ABC",
+ },
+ {"n_factors": 8, "n_generators": 1, "generator": "H = ABCDEFG"},
+ {"n_factors": 8, "n_generators": 2, "generator": "G = ABCD ; H = ABEF"},
+ {
+ "n_factors": 8,
+ "n_generators": 3,
+ "generator": "F = ABC ; G = ABD ; H = BCDE",
+ },
+ {
+ "n_factors": 8,
+ "n_generators": 4,
+ "generator": "E = BCD ; F = ACD ; G = ABC ; H = ABD ",
+ },
+ {"n_factors": 9, "n_generators": 2, "generator": "H = ACDFG ; J = BCEFG"},
+ {
+ "n_factors": 9,
+ "n_generators": 3,
+ "generator": "G = ABCD ; H = ACEF ; J = CDEF",
+ },
+ {
+ "n_factors": 9,
+ "n_generators": 4,
+ "generator": "F = BCDE ; G = ACDE ; H = ABDE ; J = ABCE",
+ },
+ {
+ "n_factors": 9,
+ "n_generators": 5,
+ "generator": "E = ABC ; F = BCD ; G = ACD ; H = ABD ; J = ABCD ",
+ },
+ {
+ "n_factors": 10,
+ "n_generators": 3,
+ "generator": "H = ABCG ; J = BCDE ; K = ACDF",
+ },
+ {
+ "n_factors": 10,
+ "n_generators": 4,
+ "generator": "G = BCDF ; H = ACDF ; J = ABDE ; K = ABCE ",
+ },
+ {
+ "n_factors": 10,
+ "n_generators": 5,
+ "generator": "F = ABCD ; G = ABCE ; H = ABDE ; J = ACDE ; K = BCDE ",
+ },
+ {
+ "n_factors": 10,
+ "n_generators": 6,
+ "generator": "E = ABC ; F = BCD ; G = ACD ; H = ABD ; J = ABCD ; K = AB ",
+ },
+ {
+ "n_factors": 11,
+ "n_generators": 4,
+ "generator": "H = ABCG ; J = BCDE ; K = ACDF ; L = ABCDEFG",
+ },
+ {
+ "n_factors": 11,
+ "n_generators": 5,
+ "generator": "G = CDE ; H = ABCD ; J = ABF ; K = BDEF ; L = ADEF ",
+ },
+ {
+ "n_factors": 11,
+ "n_generators": 6,
+ "generator": "F = ABC ; G = BCD ; H = CDE ; J = ACD ; K = ADE ; L = BDE ",
+ },
+ {
+ "n_factors": 11,
+ "n_generators": 7,
+ "generator": "E = ABC ; F = BCD ; G = ACD ; H = ABD ; J = ABCD ; K = AB ; L = AC ",
+ },
+ {
+ "n_factors": 12,
+ "n_generators": 5,
+ "generator": "H = ACDG ; J = ABCD ; K = BCFG ; L = ABDEFG ; M = CDEF",
+ },
+ {
+ "n_factors": 12,
+ "n_generators": 6,
+ "generator": "G = DEF ; H = ABC ; J = BCDE ; K = BCDF ; L = ABEF ; M = ACEF",
+ },
+ {
+ "n_factors": 12,
+ "n_generators": 7,
+ "generator": "F = ACE ; G = ACD ; H = ABD ; J = ABE ; K = CDE ; L = ABCDE ; M = ADE ",
+ },
+ {
+ "n_factors": 12,
+ "n_generators": 8,
+ "generator": "E = ABC ; F = ABD ; G = ACD ; H = BCD ; J = ABCD ; K = AB ; L = AC ; M = AD ",
+ },
+ {
+ "n_factors": 13,
+ "n_generators": 6,
+ "generator": "H = DEFG ; J = BCEG ; K = BCDFG ; L = ABDEF ; M = ACEF ; N = ABC ",
+ },
+ {
+ "n_factors": 13,
+ "n_generators": 7,
+ "generator": "G = ABC ; H = DEF ; J = BCDF ; K = BCDE ; L = ABEF ; M = ACEF ; N = BCEF ",
+ },
+ {
+ "n_factors": 13,
+ "n_generators": 8,
+ "generator": "F = ACE ; G = BCE ; H = ABC ; J = CDE ; K = ABCDE ; L = ABE ; M = ACD ; N = ADE ",
+ },
+ {
+ "n_factors": 13,
+ "n_generators": 9,
+ "generator": "E = ABC ; F = ABD ; G = ACD ; H = BCD ; J = ABCD ; K = AB ; L = AC ; M = AD ; N = BC ",
+ },
+ {
+ "n_factors": 14,
+ "n_generators": 7,
+ "generator": "H = EFG ; J = BCFG ; K = BCEG ; L = ABEF ; M = ACEF ; N = BCDEF ; O = ABC ",
+ },
+ {
+ "n_factors": 14,
+ "n_generators": 8,
+ "generator": "G = BEF ; H = BCF ; J = DEF ; K = CEF ; L = BCE ; M = CDF ; N = ACDE ; O = BCDEF ",
+ },
+ {
+ "n_factors": 14,
+ "n_generators": 9,
+ "generator": "F = ABC ; G = ABD ; H = ABE ; J = ACD ; K = ACE ; L = ADE ; M = BCD ; N = BCE ; O = BDE ",
+ },
+ {
+ "n_factors": 14,
+ "n_generators": 10,
+ "generator": "E = ABC ; F = ABD ; G = ACD ; H = BCD ; J = ABCD ; K = AB ; L = AC ; M = AD ; N = BC ; O = BD ",
+ },
+ {
+ "n_factors": 15,
+ "n_generators": 8,
+ "generator": "H = ABFG ; J = ACDEF ; K = BEF ; L = ABCEG ; M = CDFG ; N = ACDEG ; O = EFG ; P = ABDEFG ",
+ },
+ {
+ "n_factors": 15,
+ "n_generators": 9,
+ "generator": "G = ABC ; H = ABD ; J = ABE ; K = BCDE ; L = ACF ; M = ADF ; N = AEF ; O = CDEF ; P = ABCDEF",
+ },
+ {
+ "n_factors": 15,
+ "n_generators": 10,
+ "generator": "F = ABC ; G = ABD ; H = ABE ; J = ACD ; K = ACE ; L = ADE; M = BCD ; N = BCE ; O = BDE; P = CDE",
+ },
+ {
+ "n_factors": 15,
+ "n_generators": 11,
+ "generator": "E = ABC ; F = ABD ; G = ACD ; H = BCD ; J = ABCD ; K = AB ; L = AC ; M = AD ; N = BC ; O = BD ; P = CD ",
+ }, # type: ignore
+ ]
+)

bofire/utils/doe.py

@@ -9,6 +9,7 @@
 
 from bofire.data_models.domain.api import Inputs
 from bofire.data_models.features.api import CategoricalInput, ContinuousInput
+from bofire.utils.default_fracfac_generators import default_fracfac_generators
 
 
 def get_confounding_matrix(
@@ -224,7 +225,42 @@ def get_alias_structure(gen: str, order: int = 4) -> List[str]:
  return aliases_readable
 
 
-def get_generator(n_factors: int, n_generators: int) -> str:
+def get_default_generator(n_factors: int, n_generators: int) -> str:
+ """Returns the default generator for a given number of factors and generators.
+
+ In case the combination is not available, the function will raise an error.
+
+ Args:
+ n_factors: The number of factors.
+ n_generators: The number of generators.
+
+ Returns:
+ The generator.
+ """
+ if n_generators == 0:
+ return " ".join(list(string.ascii_lowercase[:n_factors]))
+ df_generators = default_fracfac_generators
+ n_base_factors = n_factors - n_generators
+ if df_generators.loc[
+ (df_generators.n_factors == n_factors)
+ & (df_generators.n_generators == n_generators)
+ ].empty:
+ raise ValueError("No generator available for the requested combination.")
+ generators = (
+ df_generators.loc[
+ (df_generators.n_factors == n_factors)
+ & (df_generators.n_generators == n_generators),
+ "generator",
+ ]
+ .to_list()[0]
+ .split(";")
+ )
+ assert len(generators) == n_generators, "Number of generators does not match."
+ generators = [generator.split("=")[1].strip().lower() for generator in generators]
+ return " ".join(list(string.ascii_lowercase[:n_base_factors]) + generators)
+
+
+def compute_generator(n_factors: int, n_generators: int) -> str:
  """Computes a generator for a given number of factors and generators.
 
  Args:
@@ -268,3 +304,22 @@ def get_generator(n_factors: int, n_generators: int) -> str:
  "Design not possible, as main factors are confounded with each other."
  )
  return " ".join(list(string.ascii_lowercase[:n_base_factors]) + generators)
+
+
+def get_generator(n_factors: int, n_generators: int) -> str:
+ """Returns a generator for a given number of factors and generators.
+
+ If the requested combination is available in the default generators, it will return
+ this one. Otherwise, it will compute a new one using `get_bofire_generator`.
+
+ Args:
+ n_factors: The number of factors.
+ n_generators: The number of generators.
+
+ Returns:
+ The generator.
+ """
+ try:
+ return get_default_generator(n_factors, n_generators)
+ except ValueError:
+ return compute_generator(n_factors, n_generators)

tests/bofire/utils/test_doe.py

@@ -3,11 +3,14 @@
 
 from bofire.data_models.domain.api import Inputs
 from bofire.data_models.domain.features import ContinuousInput
+from bofire.utils.default_fracfac_generators import default_fracfac_generators
 from bofire.utils.doe import (
+ compute_generator,
  ff2n,
  fracfact,
  get_alias_structure,
  get_confounding_matrix,
+ get_default_generator,
  get_generator,
  validate_generator,
 )
@@ -159,17 +162,34 @@ def test_validate_generator_invalid(n_factors: int, generator: str, message: str
  (8, 4, "a b c d abc abd acd bcd"),
  ],
 )
-def test_get_generator(n_factors, n_generators, expected):
- assert get_generator(n_factors, n_generators) == expected
+def test_compute_generator(n_factors, n_generators, expected):
+ assert compute_generator(n_factors, n_generators) == expected
 
 
 @pytest.mark.parametrize(
  "n_factors, n_generators",
  [(2, 1), (3, 2), (4, 3), (4, 2), (5, 3), (6, 4), (7, 5), (8, 5)],
 )
-def test_get_generator_invalid(n_factors, n_generators):
+def test_compute_generator_invalid(n_factors, n_generators):
  with pytest.raises(
  ValueError,
  match="Design not possible, as main factors are confounded with each other.",
  ):
- get_generator(n_factors, n_generators)
+ compute_generator(n_factors, n_generators)
+
+
+def test_get_default_generator():
+ for _, row in default_fracfac_generators.iterrows():
+ n_factors = row["n_factors"]
+ n_generators = row["n_generators"]
+ g = get_default_generator(n_factors, n_generators)
+ validate_generator(n_factors, g)
+ with pytest.raises(
+ ValueError, match="No generator available for the requested combination."
+ ):
+ get_default_generator(100, 1)
+
+
+def test_get_generator():
+ assert get_generator(6, 2) != compute_generator(6, 2)
+ assert get_generator(16, 1) == compute_generator(16, 1)