pg.iter

Accessible via pg.iter, pg.hyper.iterate.

iterate(hyper_value, num_examples=None, algorithm=None, where=None, force_feedback=False)[source]

Iterate a hyper value based on an algorithm.

Example:

hyper_dict = pg.Dict(x=pg.oneof([1, 2, 3]), y=pg.oneof(['a', 'b']))

# Get all examples from the hyper_dict.
assert list(pg.iter(hyper_dict)) == [
    pg.Dict(x=1, y='a'),
    pg.Dict(x=1, y='b'),
    pg.Dict(x=2, y='a'),
    pg.Dict(x=2, y='b'),
    pg.Dict(x=3, y='a'),
    pg.Dict(x=3, y='b'),
]

# Get the first two examples.
assert list(pg.iter(hyper_dict, 2)) == [
    pg.Dict(x=1, y='a'),
    pg.Dict(x=1, y='b'),
]

# Random sample examples, which is equivalent to `pg.random_sample`.
list(pg.iter(hyper_dict, 2, pg.geno.Random()))

# Iterate examples with feedback loop.
for d, feedback in pg.iter(
    hyper_dict, 10,
    pg.evolution.regularized_evolution(pg.evolution.mutators.Uniform())):
  feedback(d.x)

# Only materialize selected parts.
assert list(
    pg.iter(hyper_dict, where=lambda x: len(x.candidates) == 2)) == [
        pg.Dict(x=pg.oneof([1, 2, 3]), y='a'),
        pg.Dict(x=pg.oneof([1, 2, 3]), y='b'),
    ]

pg.iter distinguishes from pg.sample in that it’s designed for simple in-process iteration, which is handy for quickly generating examples from algorithms without maintaining trail states. On the contrary, pg.sample is designed for distributed sampling, with parallel workers and failover handling.

Parameters:

  • hyper_value – A hyper value that represents a space of instances.

  • num_examples – An optional integer as the max number of examples to propose. If None, propose will return an iterator of infinite examples.

  • algorithm – An optional DNA generator. If None, Sweeping will be used, which iterates examples in order.

  • where – Function to filter hyper primitives. If None, all hyper primitives from value will be included in the encoding/decoding process. Otherwise only the hyper primitives on which ‘where’ returns True will be included. where can be useful to partition a search space into separate optimization processes. Please see ‘Template’ docstr for details.

  • force_feedback – If True, always return the Feedback object together with the example, this is useful when the user want to pass different DNAGenerators to pg.iter and want to handle them uniformly.

Yields:

A tuple of (example, feedback_fn) if the algorithm needs a feedback or force_feedback is True, otherwise the example.

Raises:

ValueError – when hyper_value is a constant value.