pg.DNASpec¶

Accessible via pg.DNASpec, pg.geno.DNASpec.

class DNASpec(location=, hints=None)[source]¶

Bases: pg.Object

Base class for DNA specifications (genotypes).

A DNASpec object describes the rules and tips for generating a DNA.

pg.geno.Space: Represents a space or sub-space, which contains a list of decision points.

pg.geno.DecisionPoint: Represents a concrete decision point.

Concrete decision points are the following:

pg.geno.Choices: Represents a single categorical choice or multiple related categorical choices. Each candidate is a sub-space.

pg.geno.Float: Represents a continuous float value within a range.

pg.geno.CustomDecisionPoint: Represents the genotype for a pg.hyper.CustomHyper.

All DecisionPoints provide hints for DNA generator as a reference when generating values, it needs to be serializable to pass between client and servers.

All DNASpec types allow user to attach their data via set_userdata method, it’s aimed to be used within the same process, thus not required to be serializable.

Attributes:

`decision_ids`	Returns decision IDs.
`decision_points`	Returns all decision points in their declaration order.
`id`	Returns a path of locations from the root as the ID for current node.
`is_categorical`	Returns True if current node is a categorical choice.
`is_custom_decision_point`	Returns True if current node is a custom decision point.
`is_numerical`	Returns True if current node is numerical decision.
`is_space`	Returns True if current node is a sub-space.
`is_subchoice`	Returns True if current node is a subchoice of a multi-choice.
`named_decision_points`	Returns all named decision points in their declaration order.
`parent_choice`	Returns the parent choice of current space.
`parent_spec`	Returns parent spec.
`space_size`	Returns the size of the search space.
`userdata`	Gets user data.

Methods:

`first_dna`([attach_spec])	Returns the first DNA in the spec.
`from_json`(json_value, args, *kwargs)	Override from_json for backward compatibility with serialized data.
`get`(name_or_id[, default])	Get decision point(s) by name or ID.
`iter_dna`([dna, attach_spec])	Iterate the DNA in the space represented by this spec.
`next_dna`([dna, attach_spec])	Returns the next DNA in the space represented by this spec.
`random_dna`([random_generator, attach_spec, ...])	Returns a random DNA based on current spec.
`set_userdata`(key, value)	Sets user data.
`validate`(dna)	Validate whether a DNA value conforms to this spec.

property decision_ids: List[KeyPath][source]¶: Returns decision IDs.

abstract property decision_points: List[DecisionPoint][source]¶: Returns all decision points in their declaration order.

first_dna(attach_spec=True)[source]¶

Returns the first DNA in the spec.

Return type:: pg.DNA

classmethod from_json(json_value, *args, **kwargs)[source]¶

Override from_json for backward compatibility with serialized data.

Return type:: pg.Object

get(name_or_id, default=None)[source]¶

Get decision point(s) by name or ID.

Return type:: Union[pg.geno.DecisionPoint, List[pg.geno.DecisionPoint]]

property id: KeyPath[source]¶: Returns a path of locations from the root as the ID for current node.

abstract property is_categorical: bool[source]¶: Returns True if current node is a categorical choice.

abstract property is_custom_decision_point: bool[source]¶: Returns True if current node is a custom decision point.

abstract property is_numerical: bool[source]¶: Returns True if current node is numerical decision.

abstract property is_space: bool[source]¶: Returns True if current node is a sub-space.

abstract property is_subchoice: bool[source]¶: Returns True if current node is a subchoice of a multi-choice.

iter_dna(dna=None, attach_spec=True)[source]¶

Iterate the DNA in the space represented by this spec.

Parameters:

dna – An optional DNA as the start point (exclusive) for iteration.
attach_spec – If True, the DNASpec will be attached to the DNA returned.

Yields:

The next DNA according to the spec.

property named_decision_points: Dict[str, DecisionPoint | List[DecisionPoint]][source]¶: Returns all named decision points in their declaration order.

next_dna(dna=None, attach_spec=True)[source]¶

Returns the next DNA in the space represented by this spec.

Return type:

Optional[pg.DNA]

Parameters:

dna – The DNA whose next will be returned. If None, next_dna will return the first DNA.
attach_spec – If True, current spec will be attached to the returned DNA.

Returns:

The next DNA or None if there is no next DNA.

property parent_choice: DecisionPoint | None[source]¶: Returns the parent choice of current space.

property parent_spec: DNASpec | None[source]¶: Returns parent spec. None if spec is root.

random_dna(random_generator=None, attach_spec=True, previous_dna=None)[source]¶

Returns a random DNA based on current spec.

Return type:

pg.DNA

Parameters:

random_generator – An optional Random object. If None, the global random module will be used.
attach_spec – If True, current spec will be attached to the returned DNA.
previous_dna – An optional DNA representing previous DNA. This field might be useful for generating stateful random DNAs.

Returns:

A random DNA based on current spec.

set_userdata(key, value)[source]¶

Sets user data.

User data can be used for storing state associated with the DNASpec, and is not persisted across processes or during serialization. Use hints to carry persistent objects for the DNASpec.

Return type:

None

Parameters:

key – Key of the user data.
value – Value of the user data.

abstract property space_size: int[source]¶: Returns the size of the search space. Use -1 for infinity.

property userdata: AttributeDict[source]¶: Gets user data.

abstract validate(dna)[source]¶

Validate whether a DNA value conforms to this spec.

Return type:: bool