pg.DNAGenerator

Accessible via pg.DNAGenerator, pg.geno.DNAGenerator.

class DNAGenerator

Bases: pg.Object

Base class for DNA generator.

A DNA generator is an object that produces pg.DNA, and optionally takes feedback from the caller to improve its future proposals.

To implement a DNA generator, the user must implement the _propose method, and can optionally override the _setup, _feedback and _replay methods.

• Making proposals (Required): This method defines what to return as the next DNA from the generator, users MUST override the _propose method to implement this logic. _propose can raise StopIteration when no more DNA can be produced.

• Custom setup (Optional): Usually a DNAGenerator subclass has its internal state, which can be initialized when the search space definition is attached to the DNAGenerator. To do so, the user can override the _setup method, in which we can access the search space definition (DNASpec object) via self.dna_spec.

• Taking feedback (Optional): A DNAGenerator may take feedbacks from the caller on the fitness of proposed DNA to improve future proposals. The fitness is measured by a reward (a float number as the measure of a single objective, or a tuple of float numbers as the measure for multiple objectives). The user should override the _feedback method to implement such logics. If the reward is for multiple objectives. The user should override the multi_objective property to return True.

• State recovery (Optional): DNAGenerator was designed with distributed computing in mind, in which a process can be preempted or killed unexpectedly. Therefore, a DNAGenerator should be able to recover its state from historical proposals and rewards. The recover method was introduced for such purpose, whose default implementation is to replay the history through the _feedback method. If the user has a custom replay logic other than _feedback, they should override the _replay method. In some use cases, the user may want to implement their own checkpointing logic. In such cases, the user can override the recover method as a no-op. As aside note, the recover method will be called by the tuning backend (see tuning.py) after setup but before propose.

See also

• pg.geno.Sweeping

• pg.geno.Random

• pg.geno.dna_generator

Methods:

feedback(dna, reward)	Feedback a completed trial to the algorithm.
propose()	Propose a DNA to evaluate.
recover(history)	Recover states by replaying the proposal history.
setup(dna_spec)	Setup DNA spec.

Attributes:

multi_objective	If True, current DNA generator supports multi-objective optimization.
needs_feedback	Returns True if the DNAGenerator needs feedback.
num_feedbacks	Get number of proposals whose feedback are provided.
num_proposals	Get number of proposals that are already produced.

feedback(dna, reward)

Feedback a completed trial to the algorithm.

Return type:

None

Parameters:

• dna – a DNA object.

• reward – reward for the DNA. It is a float if self.multi_objective returns False, otherwise it’s a tuple of floats.

property multi_objective: bool

If True, current DNA generator supports multi-objective optimization.

property needs_feedback: bool

Returns True if the DNAGenerator needs feedback.

property num_feedbacks

Get number of proposals whose feedback are provided.

property num_proposals

Get number of proposals that are already produced.

propose()

Propose a DNA to evaluate.

Return type:

pg.DNA

recover(history)

Recover states by replaying the proposal history.

NOTE: recover will always be called before first propose and could be called multiple times if there are multiple source of history, e.g: trials from a previous study and existing trials from current study.

Return type:

None

Parameters:

history – An iterable object that consists of historically proposed DNA with its reward. The reward will be None if it is not yet provided (via feedback).

setup(dna_spec)

Setup DNA spec.

Return type:

None