pg.permutate¶

Accessible via pg.permutate, pg.hyper.permutate.

permutate(candidates, name=None, hints=None)[source]¶

Permuatation of candidates.

Example:

@pg.members([
  ('x', pg.typing.Int())
])
class A(pg.Object):
  pass

# Permutates the candidates.
v = pg.permutate([1, 2, 3])

# A complex type as candidate.
v1 = pg.permutate(['a', {'x': 1}, A(1)])

# A hierarchical categorical choice:
v2 = pg.permutate([
    'foo',
    'bar',
    A(pg.oneof([1, 2, 3]))
])

Return type:: Any

Note

Under symbolic mode (by default), pg.manyof returns a pg.hyper.ManyOf object. Under dynamic evaluate mode, which is called under the context of pg.hyper.DynamicEvaluationContext or pg.hyper.DynamicEvaluationContext, it evaluates to a concrete candidate value.

To use conditional search space in dynamic evaluate mode, the candidate should be wrapped with a lambda function, which is not necessary under symbolic mode. For example:

pg.permutate([
   lambda: pg.oneof([0, 1], name='sub_a'),
   lambda: pg.floatv(0.0, 1.0, name='sub_b'),
   lambda: pg.manyof(2, ['a', 'b', 'c'], name='sub_c')
], name='root')

See also

Parameters:

candidates – Candidates to select from. Items of candidate can be any type, therefore it can have nested hyper primitives, which forms a hierarchical search space.
name – A name that can be used to identify a decision point in the search space. This is needed when the code to instantiate the same hyper primitive may be called multiple times under a pg.DynamicEvaluationContext.collect context or a pg.DynamicEvaluationContext.apply context.
hints – An optional value which acts as a hint for the controller.

Returns:

In symbolic mode, this function returns a Choices. In dynamic evaluate mode, this function returns a permutation from candidates. If evaluated under an pg.DynamicEvaluationContext.apply scope, this function will return a permutation of candidates based on controller decisions. If evaluated under a pg.DynamicEvaluationContext.collect scope, it will return the first valid permutation. For example:

# Evaluates to [0, 1, 2, 3, 4].
permutate(range(5), name='numbers')