pygx.geno

Program genome and genotypes.

geno

Program genome and genotypes.

A program genome (pg.DNA) encodes the decisions that generate a concrete object from a search space. Genotypes (pygx.DNASpec) are the specifications of how to generate them. Genotypes are separated from their corresponding hyper values (pygx.HyperValue), which generate the client-side objects, so that the algorithms that generate genomes are decoupled from the programs that consume them. As a result, the same algorithm can be applied to different user programs for optimization.

classDiagram
  DNASpec <|-- Space
  DNASpec <|-- DecisionPoint
  Space *-- DecisionPoint : elements
  DecisionPoint <|-- Choices
  Choices *-- Space : candidates
  DecisionPoint <|-- Float
  DecisionPoint <|-- CustomDecisionPoint
  DNA *-- DNA : children
  DNA --> DNASpec : spec

Genotypes map 1:1 to hyper primitives as the following:

Genotype class	Hyper class
pg.DNASpec	pg.hyper.HyperValue
pg.geno.Space	pg.hyper.ObjectTemplate
pg.geno.DecisionPoint	pg.hyper.HyperPrimitive
pg.geno.Choices	pg.hyper.Choices (pg.oneof, pg.manyof)
pg.geno.Float	pg.floatv
pg.geno.CustomDecisionPoint	pg.hyper.CustomHyper (pg.evolve)

DNA

DNA(
    value: None | int | float | str | list[Any] | tuple[Any] = None,
    children: list[DNA] | None = None,
    spec: DNASpec | None = None,
    metadata: dict[str, Any] | None = None,
    *,
    allow_partial: bool = False,
    **kwargs: Any
)

Bases: Object

The genome of a symbolic object relative to its search space.

DNA is a hierarchical structure - each DNA node has a value, and a list of child DNA nodes. The root node represents the genome that encodes an entire object relative to its space. The value of a DNA node could be None, an integer, a float number or a string, depending on its specification (pg.DNASpec). A valid DNA has a form of the following.

Hyper value type (DNASpec type)	Possible values	Child nodes
pg.hyper.ObjectTemplate (pg.geno.Space)	None (elements > 1)	DNA of child decision points (Choices/Float) in the template.
"	None (elements == 1 and elements[0] num_choices > 1)	Children of elements[0]
"	int (elements == 1 and elements[0] num_choices == 1)	Children of the chosen candidate of elements[0]
"	float (elements == 1 and elements[0] is geno.Float)	Empty
pg.oneof (pg.geno.Choices)	int (candidate index as choice)	Children of Space for the chosen candidate
pg.manyof (pg.geno.Choices)	None (num_choices > 1)	DNA of each chosen candidate
"	int (num_choices == 1)	Children of chosen candidate
pg.floatv (pg.geno.Float)	float	Empty
pg.hyper.CustomHyper (pg.geno.CustomDecisionPoint)	str (serialized object)	User defined.

DNA can also be represented in a compact form - a tree of numbers/strs, formally defined as:

<dna> := empty | <decision>
<decision> := <single-decision>
           | <multiple-decisions>
           | <conditional-choice>
<single-decision> := <categorical-decision>
                  | <float-decision>
                  | <custom-decision>
<categorical-decision> := int
<float-decision> := float
<custom-decision> := str
<multiple-decisions> := [<decision>, <decision>, ...]
<conditional-choice> := (<categorical-decision>,
                         <categorical-decision>,
                         ...
                         <decision>)

Thus DNA can be constructed by nested structures of list, tuple and numbers. The numeric value for DNA can be integer (as index of choice) or float (the value itself will be used as decoded value).

Examples:

# Empty DNA. This may be generated by an empty template.
DNA()

# A DNA of a nested choice of depth 3: tuple items chain
# conditional decisions (0 -> 0 -> 0).
DNA((0, 0, 0))

# A DNA of three choices at the same level,
# positioned at 0, 1, 2, each choice has value 0.
DNA([0, 0, 0])

# A DNA of two choices (one two-level conditional,
# one non-conditional), position 0 is with choice path: 0 -> [0, 1],
# while [0, 1] means it's a multi-choice (e.g. `pg.manyof(2, ...)`).
# position 1 is a single non-conditional choice: 0.
DNA([(0, [0, 1]), 0])

# A DNA with custom decision point whose encoding
# is defined by the user.
DNA('abc')

Constructor.

Parameters:

Name	Type	Description	Default
value	None | int | float | str | list[Any] | tuple[Any]	Value for current node.	None
children	list[DNA] | None	Child DNA(s).	None
spec	DNASpec | None	DNA spec that constrains current node.	None
metadata	dict[str, Any] | None	Optional dict as controller metadata for the DNA.	None
allow_partial	bool	If True, allow the object to be partial.	False
**kwargs	Any	keyword arguments that will be passed through to symbolic.Object.	{}

Source code in pygx/geno/_base.py

def __init__(
    self,
    value: None | int | float | str | list[Any] | tuple[Any] = None,
    # Set MISSING_VALUE to use default from pg_typing.
    children: list['DNA'] | None = None,
    spec: DNASpec | None = None,
    metadata: dict[str, Any] | None = None,
    *,
    allow_partial: bool = False,
    **kwargs: Any,
):
    """Constructor.

    Args:
      value: Value for current node.
      children: Child DNA(s).
      spec: DNA spec that constrains current node.
      metadata: Optional dict as controller metadata for the DNA.
      allow_partial: If True, allow the object to be partial.
      **kwargs: keyword arguments that will be passed through to
        symbolic.Object.
    """
    value, children, metadata = self._parse_value_and_children(
        value, children, metadata, spec
    )
    super().__init__(
        value=value,
        children=children,
        metadata=metadata or {},
        allow_partial=allow_partial,
        **kwargs,
    )

    self._decision_by_id_cache = None
    self._named_decisions = None
    self._userdata = AttributeDict()
    self._cloneable_metadata_keys = set()
    self._cloneable_userdata_keys = set()
    self._spec = None
    if spec:
        self.use_spec(spec)

userdata property

userdata: AttributeDict

Gets user data.

spec property

spec: DNASpec | None

Returns DNA spec of current DNA.

parent_dna property

parent_dna: Optional[DNA]

Returns parent DNA.

root property

root: DNA

Returns the DNA root.

is_subchoice property

is_subchoice: bool

Returns True if current DNA is a subchoice of a multi-choice.

multi_choice_spec property

multi_choice_spec: Optional[DecisionPoint]

Returns the multi-choice spec for child DNAs.

Returns:

Type	Description
Optional[DecisionPoint]	If the children of this DNA are decisions of a multi-choice's subchoices,
Optional[DecisionPoint]	return the multi-choice spec (pg.geno.Choices). Otherwise returns None.

is_multi_choice_container property

is_multi_choice_container: bool

Returns True if the children of this DNA are multi-choice subchoices.

literal_value property

literal_value: str | int | float | list[str | int | float]

Returns the literal value represented by current DNA.

Requires the DNA to be bound with a DNASpec. Leaf decisions render as their literal value when the spec provides one, falling back to '{index}/{num_candidates}' for choices without literal values. Conditional decision chains are joined with ' -> ' (e.g. '1/2 -> 0.5'), and sibling decisions form a list.

decision_ids property

decision_ids: list[KeyPath]

Returns decision IDs.

named_decisions property

named_decisions: dict[str, Union[DNA, list[DNA]]]

Returns a dict of name to the named DNA in the sub-tree.

is_leaf property

is_leaf: bool

Returns whether the current node is a leaf node.

on_sym_bound

on_sym_bound()

Event that is triggered when any symbolic member changes.

Source code in pygx/geno/_base.py

def on_sym_bound(self):
    """Event that is triggered when any symbolic member changes."""
    super().on_sym_bound()
    self._decision_by_id_cache = None
    self._named_decisions = None

set_metadata

set_metadata(key: str, value: Any, cloneable: bool = False) -> DNA

Set metadata associated with a key.

Metadata associated with the DNA will be persisted and carried over across processes, which is different from userdata. (See set_userdata for more details.)

Parameters:

Name	Type	Description	Default
key	str	Key for the metadata.	required
value	Any	Value for the metadata.	required
cloneable	bool	If True, the key/value will be propagated during clone.	False

Returns:

Type	Description
DNA	Self.

Source code in pygx/geno/_base.py

def set_metadata(
    self, key: str, value: Any, cloneable: bool = False
) -> 'DNA':
    """Set metadata associated with a key.

    Metadata associated with the DNA will be persisted and carried over across
    processes, which is different from `userdata`. (See `set_userdata` for
    more details.)

    Args:
      key: Key for the metadata.
      value: Value for the metadata.
      cloneable: If True, the key/value will be propagated during clone.

    Returns:
      Self.
    """
    self.metadata.sym_rebind(  # pyright: ignore[reportAttributeAccessIssue]
        {key: value}, skip_notification=True
    )
    if cloneable:
        self._cloneable_metadata_keys.add(key)
    return self

set_userdata

set_userdata(key: str, value: Any, cloneable: bool = False) -> DNA

Sets user data associated with a key.

User data associated with the DNA will live only within current process, and is not carried over during serialization/deserialization, which is different from DNA metadata. (See set_metadata for more details.)

Parameters:

Name	Type	Description	Default
key	str	Key of the user data.	required
value	Any	Value of the user data.	required
cloneable	bool	If True, the key/value will be carry over to the cloned DNA.	False

Returns:

Type	Description
DNA	Self.

Source code in pygx/geno/_base.py

def set_userdata(
    self, key: str, value: Any, cloneable: bool = False
) -> 'DNA':
    """Sets user data associated with a key.

    User data associated with the DNA will live only within current process,
    and is not carried over during serialization/deserialization, which is
    different from DNA metadata. (See `set_metadata` for more details.)

    Args:
      key: Key of the user data.
      value: Value of the user data.
      cloneable: If True, the key/value will be carry over to the cloned DNA.

    Returns:
      Self.
    """
    self._userdata[key] = value
    if cloneable:
        self._cloneable_userdata_keys.add(key)
    return self

use_spec

use_spec(spec: DNASpec) -> DNA

Use a DNA spec for this node and children recursively.

Parameters:

Name	Type	Description	Default
spec	DNASpec	DNA spec.	required

Returns:

Type	Description
DNA	Self.

Raises:

Type	Description
ValueError	current DNA tree does not conform to the DNA spec.

Source code in pygx/geno/_base.py

def use_spec(self, spec: DNASpec) -> 'DNA':
    """Use a DNA spec for this node and children recursively.

    Args:
      spec: DNA spec.

    Returns:
      Self.

    Raises:
      ValueError: current DNA tree does not conform to the DNA spec.
    """
    if not isinstance(spec, DNASpec):
        raise ValueError(
            f"Argument 'spec' must be a `pg.DNASpec` object. "
            f'Encountered: {spec!r}.'
        )

    if self._spec is spec:
        return self

    def _use_spec_for_child_choices(spec: DNASpec, children: list[DNA]):
        """Use spec for child choices."""
        assert spec.is_categorical, spec
        if spec.num_choices != len(children):
            raise ValueError(
                f'Number of choices ({spec.num_choices}) does not match with '
                f'the number of child values (len(children)). '
                f'Spec: {spec!r}, Children: {children!r}.'
            )

        for i, child in enumerate(children):
            subchoice = spec.subchoice(i)
            child.use_spec(subchoice)

        child_values = cast(list[int], [c.value for c in children])
        if spec.sorted and sorted(child_values) != child_values:
            raise ValueError(
                f'Child values {child_values!r} are not sorted. Spec: {spec!r}.'
            )
        if spec.distinct and len(set(child_values)) != len(child_values):
            raise ValueError(
                f'Child values {child_values!r} are not distinct. Spec: {spec!r}.'
            )

    # Skip dummy DNA specs.
    while spec.is_space and len(spec.elements) == 1:
        spec = spec.elements[0]

    if spec.is_space:
        # Multiple value composition.
        if self.value is not None:
            raise ValueError(
                f'DNA value type mismatch. Value: {self.value}, Spec: {spec!r}.'
            )
        if len(spec.elements) != len(self.children):
            raise ValueError(
                f'Length of DNA child values ({len(self.children)}) is different '
                f'from the number of elements ({len(spec.elements)}) '
                f'in Spec: {spec!r}.'
            )
        for i, elem_spec in enumerate(spec.elements):
            self.children[i].use_spec(elem_spec)
    elif spec.is_categorical:
        if spec.num_choices == 1:
            # Single choice.
            if not isinstance(self.value, int):
                raise ValueError(
                    f'DNA value type mismatch. Value: {self.value}, Spec: {spec!r}.'
                )
            if self.value >= len(spec.candidates):
                raise ValueError(
                    f'Value of DNA is out of range according to the DNA spec. '
                    f'Value: {self.value}, Spec: {spec!r}.'
                )
            chosen_candidate = spec.candidates[self.value]
            assert chosen_candidate.is_space, chosen_candidate

            # Empty template in chosen candidate.
            if not chosen_candidate.elements and self.children:
                raise ValueError(
                    f'There is no DNA spec for child DNA values. '
                    f'Child values: {self.children}.'
                )

            # None-empty template in chosen candidate.
            if len(chosen_candidate.elements) > 1:
                # Children are DNA of multiple encoders in chosen composition.
                if len(chosen_candidate.elements) != len(self.children):
                    raise ValueError(
                        f'Number of elements in child templates '
                        f'({len(chosen_candidate.elements)}) does not match with '
                        f'the length of children ({len(self.children)}) from DNA: '
                        f'{self!r}, Spec: {chosen_candidate}.'
                    )
                for i, elem_spec in enumerate(chosen_candidate.elements):
                    self.children[i].use_spec(elem_spec)
            elif len(chosen_candidate.elements) == 1:
                # Children are multiple choices of the only encoder
                # in chosen composition.
                sub_spec = chosen_candidate
                while sub_spec.is_space and len(sub_spec.elements) == 1:
                    sub_spec = sub_spec.elements[0]
                if (
                    sub_spec.is_numerical
                    or sub_spec.is_custom_decision_point
                ):
                    if len(self.children) != 1:
                        raise ValueError(
                            f'Encountered more than 1 value.'
                            f'Child value: {self.children}, Spec: {sub_spec}.'
                        )
                    self.children[0].use_spec(sub_spec)
                else:
                    assert sub_spec.is_categorical, sub_spec
                    _use_spec_for_child_choices(sub_spec, self.children)
        else:
            # Multiple choices.
            if self.value is not None:
                raise ValueError(
                    f'Cannot apply multi-choice DNA spec on '
                    f'value {self.value}: {spec!r}.'
                )
            _use_spec_for_child_choices(spec, self.children)
    elif spec.is_numerical:
        if not isinstance(self.value, float):
            raise ValueError(
                f'DNA value type mismatch. Value: {self.value}, '
                f'Spec: {spec!r}.'
            )
        if self.value < spec.min_value:
            raise ValueError(
                f'DNA value should be no less than {spec.min_value}. '
                f'Encountered {self.value}, Spec: {spec!r}.'
            )
        if self.value > spec.max_value:
            raise ValueError(
                f'DNA value should be no greater than {spec.max_value}. '
                f'Encountered {self.value}, Spec: {spec!r}.'
            )
    else:
        assert spec.is_custom_decision_point, spec
        if not isinstance(self.value, str):
            raise ValueError(
                f'DNA value type mismatch, Value: {self.value!r}, Spec: {spec!r}.'
            )
    self._spec = spec
    return self

parse classmethod

parse(
    json_value: int | float | str | list[Any] | tuple[Any] | None,
    spec: DNASpec | None = None,
) -> DNA

Parse DNA from a nested structure of numbers.

Deprecated: use DNA.__init__ instead.

Parameters:

Name	Type	Description	Default
json_value	int | float | str | list[Any] | tuple[Any] | None	A nested structure of numbers.	required
spec	DNASpec | None	DNA spec that will be applied to current DNA tree.	None

Returns:

Type	Description
DNA	an instance of DNA object.

Raises:

Type	Description
ValueError	Bad format for json_value or parsed DNA does not conform to the DNA spec.

Source code in pygx/geno/_base.py

@classmethod
def parse(
    cls,
    json_value: (
        int  # As a single chosen index.
        | float  # As a single chosen value.
        | str  # As a custom genome.
        | list[Any]  # As multi-choice. (coexisting)
        | tuple[Any]  # As a conditional choice.
        | None  # An empty DNA.
    ),
    spec: DNASpec | None = None,
) -> 'DNA':
    """Parse DNA from a nested structure of numbers.

    Deprecated: use `DNA.__init__` instead.

    Args:
      json_value: A nested structure of numbers.
      spec: DNA spec that will be applied to current DNA tree.

    Returns:
      an instance of DNA object.

    Raises:
      ValueError: Bad format for json_value or parsed DNA does not conform to
        the DNA spec.
    """
    return DNA(json_value, spec=spec)

from_dict classmethod

from_dict(
    dict_repr: dict[Any, Any],
    dna_spec: DNASpec,
    use_ints_as_literals: bool = False,
) -> DNA

Create a DNA from its dictionary representation.

Example:

spec = pg.geno.space([
  pg.geno.oneof(
    [pg.geno.constant(), pg.geno.constant()],
    location='x', literal_values=['a', 'b']),
  pg.geno.floatv(0.0, 1.0, location='y'),
])

# Values as candidate indices.
dna = pg.DNA.from_dict({'x': 1, 'y': 0.5}, spec)
assert dna == pg.DNA([1, 0.5])

# Values as literal values.
dna = pg.DNA.from_dict({'x': 'b', 'y': 0.5}, spec)
assert dna == pg.DNA([1, 0.5])

Parameters:

Name	Type	Description	Default
dict_repr	dict[Any, Any]	The dictionary representation of the DNA. The keys should be either strings as the decision point ID/name or DNASpec objects. The values should be either numeric or literal values for the decisions. For inactive decisions, their ID/spec should either be absent from the dictionary, or use None as their values.	required
dna_spec	DNASpec	The DNASpec that applies to the DNA.	required
use_ints_as_literals	bool	If True, when an integer is encountered for a dictionary value, treat it as the literal value. Otherwise, always treat it as a candidate index.	False

Returns:

Type	Description
DNA	A DNA object.

Source code in pygx/geno/_base.py

@classmethod
def from_dict(
    cls,
    dict_repr: dict[Any, Any],
    dna_spec: DNASpec,
    use_ints_as_literals: bool = False,
) -> 'DNA':
    """Create a DNA from its dictionary representation.

    **Example:**

    ```python
    spec = pg.geno.space([
      pg.geno.oneof(
        [pg.geno.constant(), pg.geno.constant()],
        location='x', literal_values=['a', 'b']),
      pg.geno.floatv(0.0, 1.0, location='y'),
    ])

    # Values as candidate indices.
    dna = pg.DNA.from_dict({'x': 1, 'y': 0.5}, spec)
    assert dna == pg.DNA([1, 0.5])

    # Values as literal values.
    dna = pg.DNA.from_dict({'x': 'b', 'y': 0.5}, spec)
    assert dna == pg.DNA([1, 0.5])
    ```

    Args:
      dict_repr: The dictionary representation of the DNA.
        The keys should be either strings as the decision point ID/name
        or DNASpec objects. The values should be either numeric or literal
        values for the decisions.
        For inactive decisions, their ID/spec should either be absent from the
        dictionary, or use None as their values.
      dna_spec: The DNASpec that applies to the DNA.
      use_ints_as_literals: If True, when an integer is encountered for
        a dictionary value, treat it as the literal value.
        Otherwise, always treat it as a candidate index.

    Returns:
      A DNA object.
    """

    def _get_decision(spec: DNASpec):
        """Gets the decision for DNASpec."""
        decision = dict_repr.get(spec.id, None)
        if decision is None:
            decision = dict_repr.get(spec, None)

        if decision is None and spec.name:
            decision = dict_repr.get(spec.name, None)
            # A spec can result in multiple decision points (e.g. multi-choices)
            # therefore we always pop up the next single decision if a name
            # is associated with multiple decisions.
            if isinstance(decision, list):
                dict_repr[spec.name] = decision[1:]
                decision = decision[0] if decision else None
        return decision

    def _choice_index(subchoice, value: int | float | str) -> int:
        """Gets the index of choice value based on its spec."""
        if isinstance(value, int) and not use_ints_as_literals:
            index = value
            if index < 0 or index >= len(subchoice.candidates):
                identifier = subchoice.name or subchoice.id
                raise ValueError(
                    f"Candidate index out of range at choice '{identifier}'. Index="
                    f'{index}, Number of candidates={len(subchoice.candidates)}.'
                )
        else:
            index = subchoice.candidate_index(value)
        return index

    def _make_dna(spec: DNASpec) -> DNA:
        """Lookup DNA value from parameter values according to DNA spec."""
        if spec.is_space:
            children = [_make_dna(elem) for elem in spec.elements]
            return DNA(None, children)
        else:
            if spec.is_categorical:
                children = []
                for choice_idx in range(spec.num_choices):
                    subchoice = spec.subchoice(choice_idx)
                    value = _get_decision(subchoice)

                    # It's possible that the decisions for multiple choices are
                    # collapsed as a single entry in the dictionary. e.g: {'x': [0, 1]}.
                    # In this case, we will make another attempt to get the decision
                    # from the parent spec entry.
                    if value is None and subchoice.is_subchoice:
                        parent_decisions = _get_decision(spec)
                        if parent_decisions is not None:
                            assert (
                                len(parent_decisions) == spec.num_choices
                            ), (parent_decisions, spec)
                            value = parent_decisions[choice_idx]

                    if value is None:
                        identifier = subchoice.name or subchoice.id
                        raise ValueError(
                            f"Value for '{identifier}' is not found in "
                            f'the dictionary {dict_repr!r}.'
                        )

                    if isinstance(value, DNA):
                        # A caller-supplied DNA: the input dict keeps
                        # referencing it, so this DNA takes its own copy
                        # — handled by `children`'s `assign='adopt'`.
                        children.append(value)
                    else:
                        choice_index = _choice_index(subchoice, value)
                        subspace_dna = _make_dna(
                            subchoice.candidates[choice_index]
                        )
                        children.append(
                            DNA(
                                choice_index,
                                [subspace_dna] if subspace_dna else [],
                            )
                        )
                return DNA(None, children)
            elif spec.is_numerical or spec.is_custom_decision_point:
                value = _get_decision(spec)
                if value is None:
                    raise ValueError(
                        f"Value for '{spec.name or spec.id}' is not found "
                        f'in the dictionary {dict_repr!r}.'
                    )
                if isinstance(value, DNA):
                    value = value.value
                if spec.is_numerical:
                    if value < spec.min_value:
                        raise ValueError(
                            f"The decision for '{spec.name or spec.id}' should "
                            f'be no less than {spec.min_value}. Encountered {value}.'
                        )
                    if value > spec.max_value:
                        raise ValueError(
                            f"The decision for '{spec.name or spec.id}' should "
                            f'be no greater than {spec.max_value}. Encountered {value}.'
                        )
                else:
                    if not isinstance(value, str):
                        raise ValueError(
                            f"The decision for '{spec.name or spec.id}' should "
                            f'be a string. Encountered {value}.'
                        )
                return DNA(value, None)
            else:
                raise NotImplementedError(
                    'Should never happen.'
                )  # pragma: no cover

    dna = _make_dna(dna_spec)
    return dna.use_spec(dna_spec)

to_dict

to_dict(
    key_type: str = "id",
    value_type: str = "value",
    multi_choice_key: str = "subchoice",
    include_inactive_decisions: bool = False,
    filter_fn: Callable[[DecisionPoint], bool] | None = None,
) -> dict[
    DecisionPoint | str,
    Union[None, DNA, float, int, str, list[DNA], list[int], list[str]],
]

Returns the dict representation of current DNA.

Example:

spec = pg.geno.space([
  pg.geno.oneof(
    [pg.geno.constant(), pg.geno.constant()],
    location='x', literal_values=['a', 'b']),
  pg.geno.floatv(0.0, 1.0, location='y'),
])
dna = pg.DNA([1, 0.5], spec=spec)
assert dna.to_dict() == {'x': 1, 'y': 0.5}
assert dna.to_dict(value_type='literal') == {'x': 'b', 'y': 0.5}

Parameters:

Name	Type	Description	Default
key_type	str	Key type in returned dictionary. Acceptable values are: 'id': Use the ID (canonical location) of each decision point as key. This is the default behavior. 'name_or_id': Use the name of each decision point as key if it's present, otherwise use ID as key. When the name of a decision point is presented, it is guaranteed not to clash with other decision points' names or IDs. 'dna_spec': Use the DNASpec object of each decision point as key.	'id'
value_type	str	Value type for choices in returned dictionary. Acceptable values are: 'value': Use the index of the chosen candidate for Choices, and use the float number for Float. This is the default behavior. 'dna': Use DNA for all decision points. 'choice': Use '{index}/{num_candidates}' for the chosen candidate for Choices, and the chosen float number for Float. 'literal': Use the literal value for the chosen candidate for Choices, and the chosen float number for Float. If the literal value for the Choices decision point is not present, fall back to the '{index}/{num_candidates}' format. 'choice_and_literal': Use '{index}/{num_candidates} ({literal})' for the chosen candidate for Choices and then chosen float number for Float. If the literal value for the Choices decision point is not present, fall back to the '{index}/{num_candidates}' format.	'value'
multi_choice_key	str	'subchoice', 'parent', or 'both'. If 'subchoice', each subchoice will insert a key into the dict. If 'parent', subchoices of a multi-choice will share the parent spec as key, its value will be a list of decisions from the subchoices. If 'both', the dict will contain both the keys for subchoices and the key for the parent multi-choice.	'subchoice'
include_inactive_decisions	bool	If True, inactive decisions from the search space will be added to the dict with value None. Otherwise they will be absent in the dict.	False
filter_fn	Callable[[DecisionPoint], bool] | None	Decision point filter. If None, all the decision points will be included in the dict. Otherwise only the decision points that pass the filter (returns True) will be included.	None

Returns:

Type	Description
dict[DecisionPoint | str, Union[None, DNA, float, int, str, list[DNA], list[int], list[str]]]	A dictionary of requested key type to value type mapped from the DNA.

Raises:

Type	Description
ValueError	argument key_type or value_type is not valid, or the DNA is not bound with a DNASpec.

Source code in pygx/geno/_base.py

def to_dict(
    self,
    key_type: str = 'id',
    value_type: str = 'value',
    multi_choice_key: str = 'subchoice',
    include_inactive_decisions: bool = False,
    filter_fn: Callable[[DecisionPoint], bool] | None = None,
) -> dict[
    DecisionPoint | str,
    Union[None, 'DNA', float, int, str, list['DNA'], list[int], list[str]],
]:
    """Returns the dict representation of current DNA.

    **Example:**

    ```python
    spec = pg.geno.space([
      pg.geno.oneof(
        [pg.geno.constant(), pg.geno.constant()],
        location='x', literal_values=['a', 'b']),
      pg.geno.floatv(0.0, 1.0, location='y'),
    ])
    dna = pg.DNA([1, 0.5], spec=spec)
    assert dna.to_dict() == {'x': 1, 'y': 0.5}
    assert dna.to_dict(value_type='literal') == {'x': 'b', 'y': 0.5}
    ```

    Args:
      key_type: Key type in returned dictionary. Acceptable values are:

        * 'id': Use the ID (canonical location) of each decision point as key.
          This is the default behavior.
        * 'name_or_id': Use the name of each decision point as key if it's
          present, otherwise use ID as key. When the name of a decision
          point is presented, it is guaranteed not to clash with other
          decision points' names or IDs.
        * 'dna_spec': Use the DNASpec object of each decision point as key.
      value_type: Value type for choices in returned dictionary.
        Acceptable values are:

        * 'value': Use the index of the chosen candidate for `Choices`, and
          use the float number for `Float`. This is the default behavior.
        * 'dna': Use `DNA` for all decision points.
        * 'choice': Use '{index}/{num_candidates}' for the chosen candidate
          for `Choices`, and the chosen float number for `Float`.
        * 'literal': Use the literal value for the chosen candidate for
          `Choices`, and the chosen float number for `Float`. If the literal
          value for the `Choices` decision point is not present, fall back
          to the '{index}/{num_candidates}' format.
        * 'choice_and_literal': Use '{index}/{num_candidates} ({literal})'
          for the chosen candidate for `Choices` and then chosen float number
          for `Float`. If the literal value for the `Choices` decision point
          is not present, fall back to the '{index}/{num_candidates}' format.

      multi_choice_key: 'subchoice', 'parent', or 'both'. If 'subchoice', each
        subchoice will insert a key into the dict. If 'parent', subchoices of
        a multi-choice will share the parent spec as key, its value will be
        a list of decisions from the subchoices. If 'both', the dict will
        contain both the keys for subchoices and the key for the parent
        multi-choice.
      include_inactive_decisions: If True, inactive decisions from the search
        space will be added to the dict with value None. Otherwise they will
        be absent in the dict.
      filter_fn: Decision point filter. If None, all the decision points will be
        included in the dict. Otherwise only the decision points that pass
        the filter (returns True) will be included.

    Returns:
      A dictionary of requested key type to value type mapped from the DNA.

    Raises:
      ValueError: argument `key_type` or `value_type` is not valid, or
        the DNA is not bound with a DNASpec.
    """
    if key_type not in ['id', 'name_or_id', 'dna_spec']:
        raise ValueError(
            f"'key_type' must be either 'id', 'name_or_id' "
            f"or 'dna_spec'. Encountered: {key_type!r}."
        )

    if value_type not in [
        'dna',
        'value',
        'choice',
        'literal',
        'choice_and_literal',
    ]:
        raise ValueError(
            f"'value_type' must be either 'dna', 'value', 'choice' "
            f"'literal' or 'choice_and_literal'. "
            f'Encountered: {value_type!r}.'
        )

    if multi_choice_key not in ['subchoice', 'parent', 'both']:
        raise ValueError(
            f"'multi_choice_key' must be either 'subchoice', 'parent', or "
            f"'both'. Encountered: {multi_choice_key!r}."
        )

    multi_choice_use_parent_as_key = multi_choice_key != 'subchoice'
    multi_choice_use_subchoice_as_key = multi_choice_key != 'parent'
    filter_fn = filter_fn or (lambda x: True)

    self._ensure_dna_spec()
    dict_repr = dict()

    def _needs_subchoice_key(subchoice):
        return multi_choice_use_subchoice_as_key and (
            not multi_choice_use_parent_as_key
            or (key_type != 'name_or_id' or subchoice.name is None)
        )

    def _key(spec: 'DecisionPoint'):
        if key_type == 'id':
            return spec.id.path
        elif key_type == 'name_or_id':
            return spec.name if spec.name else spec.id.path
        else:
            return spec

    def _put(key, value):
        if key in dict_repr:
            accumulated = dict_repr[key]
            if not isinstance(accumulated, list):
                accumulated = [accumulated]
            accumulated.append(value)
            value = accumulated
        dict_repr[key] = value
        return value

    def _dump_node(dna: DNA):
        """Dump node value to dict representation."""
        if isinstance(dna.spec, DecisionPoint) and filter_fn(dna.spec):
            key = _key(dna.spec)
            value = None
            if dna.spec.is_categorical and dna.value is not None:
                if value_type == 'dna':
                    value = dna
                elif value_type == 'value':
                    value = dna.value
                else:
                    value = dna.spec.format_candidate(
                        dna.value, display_format=value_type
                    )

                if dna.spec.is_subchoice:
                    # Append multi-choice values into parent's key.
                    if multi_choice_use_parent_as_key:
                        parent_spec = dna.spec.parent_spec
                        assert isinstance(parent_spec, DecisionPoint)
                        _put(_key(parent_spec), value)

                    # Insert subchoice in its own key.
                    if _needs_subchoice_key(dna.spec):
                        _put(key, value)
                else:
                    _put(key, value)
            elif dna.spec.is_numerical or dna.spec.is_custom_decision_point:
                if value_type == 'dna':
                    value = dna
                else:
                    value = dna.value
                _put(key, value)

        for child_dna in dna.children:
            _dump_node(child_dna)

    _dump_node(self)
    if not include_inactive_decisions:
        return dict_repr

    result = dict()
    assert self.spec is not None
    for dp in self.spec.decision_points:
        if not filter_fn(dp):
            continue
        if dp.is_categorical and dp.is_subchoice:
            if multi_choice_use_parent_as_key:
                if dp.subchoice_index == 0:
                    parent_spec = dp.parent_spec
                    assert isinstance(parent_spec, DecisionPoint)
                    k = _key(parent_spec)
                    result[k] = dict_repr.get(k, None)
            if _needs_subchoice_key(dp):
                k = _key(dp)
                result[k] = dict_repr.get(k, None)
        else:
            k = _key(dp)
            result[k] = dict_repr.get(k, None)
    return result

from_numbers classmethod

from_numbers(dna_values: list[int | float | str], dna_spec: DNASpec) -> DNA

Create a DNA from a flattened list of dna values.

The values are consumed by the decision points of dna_spec in DFS order — the inverse of DNA.to_numbers(flatten=True).

Example:

spec = pg.geno.space([
  pg.geno.oneof([pg.geno.constant(), pg.geno.constant()],
                location='x'),
  pg.geno.floatv(0.0, 1.0, location='y'),
])
dna = pg.DNA.from_numbers([1, 0.5], spec)
assert dna == pg.DNA([1, 0.5])
assert dna.to_numbers() == [1, 0.5]

Parameters:

Name	Type	Description	Default
dna_values	list[int | float | str]	A list of DNA values.	required
dna_spec	DNASpec	DNASpec that interprets the dna values.	required

Returns:

Type	Description
DNA	A DNA object.

Raises:

Type	Description
ValueError	The input is too short or too long for dna_spec, or a value does not conform to its decision point.

Source code in pygx/geno/_base.py

@classmethod
def from_numbers(
    cls, dna_values: list[int | float | str], dna_spec: DNASpec
) -> 'DNA':
    """Create a DNA from a flattened list of dna values.

    The values are consumed by the decision points of `dna_spec` in DFS
    order — the inverse of `DNA.to_numbers(flatten=True)`.

    **Example:**

    ```python
    spec = pg.geno.space([
      pg.geno.oneof([pg.geno.constant(), pg.geno.constant()],
                    location='x'),
      pg.geno.floatv(0.0, 1.0, location='y'),
    ])
    dna = pg.DNA.from_numbers([1, 0.5], spec)
    assert dna == pg.DNA([1, 0.5])
    assert dna.to_numbers() == [1, 0.5]
    ```

    Args:
      dna_values: A list of DNA values.
      dna_spec: DNASpec that interprets the dna values.

    Returns:
      A DNA object.

    Raises:
      ValueError: The input is too short or too long for `dna_spec`, or
        a value does not conform to its decision point.
    """
    index = 0
    n_values = len(dna_values)

    def _next_decision():
        nonlocal index
        if index >= n_values:
            raise ValueError(
                f'The input {dna_values!r} is too short for {dna_spec!r}.'
            )
        decision = dna_values[index]
        index += 1
        return decision

    def _bind_decisions(dna_spec):
        value = None
        children = None
        if dna_spec.is_space:
            children = [_bind_decisions(elem) for elem in dna_spec.elements]
        elif dna_spec.is_categorical:
            if dna_spec.num_choices == 1:
                value = _next_decision()
                assert isinstance(value, int)
                if value < 0 or value >= len(dna_spec.candidates):
                    raise ValueError(
                        f'Candidate index out of range at choice '
                        f"'{dna_spec.name or dna_spec.id}'. Index={value}, "
                        f'Number of candidates={len(dna_spec.candidates)}.'
                    )
                children = [_bind_decisions(dna_spec.candidates[value])]
            else:
                children = [
                    _bind_decisions(spec) for spec in dna_spec.choice_specs
                ]
        else:
            value = _next_decision()
        # Skip `spec=` on inner constructions: the final `use_spec` on the
        # root DNA recurses through the whole tree, so attaching spec at
        # each level would pay the dispatch cost twice.
        return DNA(value, children)

    dna = _bind_decisions(dna_spec)
    if index != n_values:
        raise ValueError(
            f'The input {dna_values!r} is too long for {dna_spec!r}. '
            f'Remaining: {dna_values[index:]!r}.'
        )
    dna.use_spec(dna_spec)
    return dna

to_numbers

to_numbers(
    flatten: bool = True,
) -> list[int | float | str] | Nestable[int | float | str]

Returns a (maybe) nested structure of numbers as decisions.

Parameters:

Name	Type	Description	Default
flatten	bool	If True, the hierarchy of the numbers will not be preserved. Decisions will be returned as a flat list in DFS order. Otherwise, a nestable structure of numbers will be returned.	True

Returns:

Type	Description
list[int | float | str] | Nestable[int | float | str]	A flat list or a hierarchical structure of numbers as the decisions made for each decision point.

Source code in pygx/geno/_base.py

def to_numbers(
    self,
    flatten: bool = True,
) -> list[int | float | str] | wire.Nestable[int | float | str]:
    """Returns a (maybe) nested structure of numbers as decisions.

    Args:
      flatten: If True, the hierarchy of the numbers will not be preserved.
        Decisions will be returned as a flat list in DFS order. Otherwise, a
        nestable structure of numbers will be returned.

    Returns:
      A flat list or a hierarchical structure of numbers as the decisions made
        for each decision point.
    """
    if flatten:
        decisions: list[int | float | str] = (
            [self.value] if self.value is not None else []
        )
        for c in self.children:
            decisions.extend(
                cast(list[int | float | str], c.to_numbers(flatten))
            )
        return decisions
    else:
        if self.value is None:
            return [c.to_numbers(flatten) for c in self.children]
        elif not self.children:
            return self.value
        elif len(self.children) == 1:
            child = self.children[0].to_numbers(flatten)
            if isinstance(child, tuple):
                return tuple([self.value, list(child)])
            else:
                return (self.value, child)
        else:
            assert len(self.children) > 1
            return (
                self.value,
                [c.to_numbers(flatten) for c in self.children],
            )

from_fn classmethod

from_fn(
    dna_spec: DNASpec,
    generator_fn: Callable[[DecisionPoint], Union[list[int], float, str, DNA]],
) -> DNA

Generate a DNA with user generator function.

Parameters:

Name	Type	Description	Default
dna_spec	DNASpec	The DNASpec for the DNA.	required
generator_fn	Callable[[DecisionPoint], Union[list[int], float, str, DNA]]	A callable object with signature: (decision_point) -> decision The decision_point is a Choices object or a Float object. The returned decision should be: a list of integer or a DNA object for a Choices decision point. When a DNA is returned, it will be used as the DNA for the entire sub-tree, hence generator_fn will not be called on sub-decision points. a float or a DNA object for a Float decision point. a string or a DNA object for a CustomDecisionPoint.	required

Example:

spec = pg.geno.space([
  pg.geno.oneof([pg.geno.constant(), pg.geno.constant()],
                location='x'),
])
dna = pg.DNA.from_fn(spec, lambda decision_point: [0])
assert dna == pg.DNA(0)

Returns:

Type	Description
DNA	A DNA generated from the user function.

Source code in pygx/geno/_base.py

@classmethod
def from_fn(
    cls,
    dna_spec: DNASpec,
    generator_fn: Callable[
        ['DecisionPoint'], Union[list[int], float, str, 'DNA']
    ],
) -> 'DNA':
    """Generate a DNA with user generator function.

    Args:
      dna_spec: The DNASpec for the DNA.
      generator_fn: A callable object with signature:

        `(decision_point) -> decision`

        The decision_point is a `Choices` object or a `Float` object.
        The returned decision should be:

         * a list of integer or a DNA object for a `Choices` decision point.
           When a DNA is returned, it will be used as the DNA for the entire
           sub-tree, hence `generator_fn` will not be called on sub-decision
           points.
         * a float or a DNA object for a Float decision point.
         * a string or a DNA object for a CustomDecisionPoint.

    **Example:**

    ```python
    spec = pg.geno.space([
      pg.geno.oneof([pg.geno.constant(), pg.geno.constant()],
                    location='x'),
    ])
    dna = pg.DNA.from_fn(spec, lambda decision_point: [0])
    assert dna == pg.DNA(0)
    ```

    Returns:
      A DNA generated from the user function.
    """
    if not isinstance(dna_spec, DNASpec):
        raise TypeError(
            f"Argument 'dna_spec' should be DNASpec type. "
            f'Encountered {dna_spec}.'
        )

    if dna_spec.is_space:
        # Generate values for Space.
        children = []
        for child_spec in dna_spec.elements:
            children.append(DNA.from_fn(child_spec, generator_fn))
        if len(children) == 1:
            return children[0]
        dna = DNA(None, children)
    elif dna_spec.is_categorical:
        assert isinstance(dna_spec, DecisionPoint), dna_spec
        decision = generator_fn(dna_spec)
        if isinstance(decision, DNA):
            dna = decision
        else:
            decision = cast(Any, decision)
            if len(decision) != dna_spec.num_choices:
                raise ValueError(
                    f'Number of DNA child values does not match the number of '
                    f'choices. Child values: {decision!r}, '
                    f'Choices: {dna_spec.num_choices}, '
                    f'Location: {dna_spec.location.path}.'
                )
            children = []
            for i, choice in enumerate(decision):
                choice_location = topology.KeyPath(i, dna_spec.location)
                if not isinstance(choice, int):
                    raise ValueError(
                        f'Choice value should be int. Encountered: {choice}, '
                        f'Location: {choice_location.path}.'
                    )
                if choice >= len(dna_spec.candidates):
                    raise ValueError(
                        f'Choice out of range. Value: {choice}, '
                        f'Candidates: {len(dna_spec.candidates)}, '
                        f'Location: {choice_location.path}.'
                    )
                child_dna = DNA.from_fn(
                    dna_spec.candidates[choice], generator_fn
                )
                children.append(DNA(choice, [child_dna]))
            dna = DNA(None, children)
    else:
        assert isinstance(dna_spec, DecisionPoint), dna_spec
        decision = generator_fn(dna_spec)
        if isinstance(decision, DNA):
            dna = decision
        else:
            dna = DNA(decision)
    dna_spec.validate(dna)
    return dna

sym_jsonify

sym_jsonify(compact: bool = True, type_info: bool = True, **kwargs: Any) -> Any

Convert DNA to JSON object.

Parameters:

Name	Type	Description	Default
compact	bool	Whether use compact form. If compact, the nested number structure in DNA.parse will be used, otherwise members will be rendered out as regular symbolic Object.	True
type_info	bool	If True, type information will be included in output, otherwise only the compact value is emitted (as a proper WireValue — tuples in their __tuple__ marker form; metadata is not attached). Applicable when compact is set to True. Note this parameter predates and shadows the to_json(type_info=...) dump option (#519) — a threaded type_info=False selects this compact value-only form.	True
**kwargs	Any	Keyword arguments that will be passed to symbolic.Object if compact is False.	{}

Returns:

Type	Description
Any	JSON representation of DNA.

Source code in pygx/geno/_base.py

def sym_jsonify(
    self, compact: bool = True, type_info: bool = True, **kwargs: Any
) -> Any:
    """Convert DNA to JSON object.

    Args:
      compact: Whether use compact form. If compact, the nested number structure
        in DNA.parse will be used, otherwise members will be rendered out as
        regular symbolic Object.
      type_info: If True, type information will be included in output, otherwise
        only the compact value is emitted (as a proper WireValue — tuples
        in their `__tuple__` marker form; `metadata` is not attached).
        Applicable when compact is set to True. Note this parameter
        predates and shadows the `to_json(type_info=...)` dump option
        (#519) — a threaded `type_info=False` selects this compact
        value-only form.
      **kwargs: Keyword arguments that will be passed to symbolic.Object if
        compact is False.

    Returns:
      JSON representation of DNA.
    """
    if not compact:
        json_value = super().sym_jsonify(**kwargs)
        assert isinstance(json_value, dict), json_value
        if self._cloneable_metadata_keys:
            json_value['_cloneable_metadata_keys'] = list(
                self._cloneable_metadata_keys
            )
        return json_value

    value = self._compact_value()
    if type_info:
        json_value = {
            wire.WireConvertible.TYPE_NAME_KEY: (
                self.__class__.__serialization_key__
            ),
            'format': 'compact',
            'value': symbolic.to_json(value),
        }
        # NOTE(daiyip): For now, we only attach metadata from the root node for
        # faster serialization/deserialization speed. This should be revised if
        # metadata for child DNA is used.
        if self.metadata:
            json_value['metadata'] = symbolic.to_json(self.metadata)

        if self._cloneable_metadata_keys:
            json_value['_cloneable_metadata_keys'] = list(
                self._cloneable_metadata_keys
            )
        return json_value
    else:
        # WireValue-clean (#531 review M2): the compact value converts
        # through `symbolic.to_json` so a raw tuple never escapes into a
        # wire payload (its `__tuple__` marker form emits instead). The
        # raw form stays available internally via `_compact_value`.
        return symbolic.to_json(value)

from_json classmethod

from_json(
    json_value: dict[str, Any],
    *,
    allow_partial: bool = False,
    root_path: KeyPath | None = None,
    **kwargs: Any
) -> DNA

Class method that load a DNA from a JSON value.

Parameters:

Name	Type	Description	Default
json_value	dict[str, Any]	Input JSON value, only JSON dict is acceptable.	required
allow_partial	bool	Whether to allow elements of the list to be partial.	False
root_path	KeyPath | None	KeyPath of loaded object in its object tree.	None
**kwargs	Any	Keyword arguments that will be passed to symbolic.from_json.	{}

Returns:

Type	Description
DNA	A DNA object.

Source code in pygx/geno/_base.py

@classmethod
def from_json(
    cls,
    json_value: dict[str, Any],
    *,
    allow_partial: bool = False,
    root_path: topology.KeyPath | None = None,
    **kwargs: Any,
) -> 'DNA':
    """Class method that load a DNA from a JSON value.

    Args:
      json_value: Input JSON value, only JSON dict is acceptable.
      allow_partial: Whether to allow elements of the list to be partial.
      root_path: KeyPath of loaded object in its object tree.
      **kwargs: Keyword arguments that will be passed to symbolic.from_json.

    Returns:
      A DNA object.
    """
    cloneable_metadata_keys = json_value.pop(
        '_cloneable_metadata_keys', None
    )
    if json_value.get('format', None) == 'compact':
        # NOTE(daiyip): DNA.parse already validates the input.
        dna = DNA.parse(
            symbolic.from_json(json_value.get('value'), **kwargs)
        )
        if 'metadata' in json_value:
            dna.sym_rebind(
                metadata=symbolic.from_json(
                    json_value.get('metadata'), **kwargs
                ),
                skip_notification=True,
            )
    else:
        dna = super().from_json(
            json_value,
            allow_partial=allow_partial,
            root_path=root_path,
            **kwargs,
        )  # pytype: disable=bad-return-type
        assert isinstance(dna, DNA)
    if cloneable_metadata_keys:
        dna._cloneable_metadata_keys = set(cloneable_metadata_keys)  # pylint: disable=protected-access
    return dna

get

get(
    key: Union[int, slice, str, KeyPath, DecisionPoint], default: Any = None
) -> Union[Any, None, DNA, list[Optional[DNA]]]

Get an immediate child DNA or DNA in the sub-tree.

Source code in pygx/geno/_base.py

def get(
    self,
    key: Union[int, slice, str, topology.KeyPath, 'DecisionPoint'],
    default: Any = None,
) -> Union[Any, None, 'DNA', list[Optional['DNA']]]:
    """Get an immediate child DNA or DNA in the sub-tree."""
    try:
        return self[key]
    except KeyError:
        return default

next_dna

next_dna() -> Optional[DNA]

Get the next DNA in the spec.

Source code in pygx/geno/_base.py

def next_dna(self) -> Optional['DNA']:
    """Get the next DNA in the spec."""
    self._ensure_dna_spec()
    assert self.spec is not None
    return self.spec.next_dna(self)

iter_dna

iter_dna()

Iterate DNA of the space starting from self.

Source code in pygx/geno/_base.py

def iter_dna(self):
    """Iterate DNA of the space starting from self."""
    self._ensure_dna_spec()
    assert self.spec is not None
    return self.spec.iter_dna(self)

format

format(
    compact: bool = False,
    verbose: bool = True,
    root_indent: int = 0,
    *,
    list_wrap_threshold: int = 80,
    as_dict: bool = False,
    **kwargs
)

Customize format method for DNA for more compact representation.

Source code in pygx/geno/_base.py

def format(
    self,
    compact: bool = False,
    verbose: bool = True,
    root_indent: int = 0,
    *,
    list_wrap_threshold: int = 80,
    as_dict: bool = False,
    **kwargs,
):
    """Customize format method for DNA for more compact representation."""
    if as_dict and self.spec:
        details = formatting.format(
            self.to_dict(value_type='choice_and_literal'),
            False,
            verbose,
            root_indent,
            **kwargs,
        )
        s = f'DNA({details})'
    else:
        kwargs['list_wrap_threshold'] = list_wrap_threshold

        if not verbose:
            s = super().format(False, verbose, root_indent, **kwargs)
        elif self.is_leaf:
            s = f'DNA({self.value!r})'
        else:
            rep = formatting.format(
                self._compact_value(),
                compact,
                verbose,
                root_indent,
                **kwargs,
            )
            if rep and rep[0] == '(':
                # NOTE(daiyip): for conditional choice from the root,
                # we don't want to keep duplicate round bracket.
                s = f'DNA{rep}'
            else:
                s = f'DNA({rep})'
    return s

parameters

parameters(use_literal_values: bool = False) -> dict[str, str]

Returns parameters for this DNA to emit based on its spec.

Deprecated: use to_dict instead.

Parameters:

Name	Type	Description	Default
use_literal_values	bool	If True, use literal values from DNASpec for Choices, otherwise returns '{choice}/{num_candidates} ({literal})'. Otherwise returns '{choice}/{num_candidates}'.	False

Returns:

Type	Description
dict[str, str]	Dict of parameter names to their values mapped from this DNA.

Raises:

Type	Description
ValueError	If the DNA is not bound with a DNASpec.

Source code in pygx/geno/_base.py

def parameters(self, use_literal_values: bool = False) -> dict[str, str]:
    """Returns parameters for this DNA to emit based on its spec.

    Deprecated: use `to_dict` instead.

    Args:
      use_literal_values: If True, use literal values from DNASpec for Choices,
        otherwise returns '{choice}/{num_candidates} ({literal})'. Otherwise
        returns '{choice}/{num_candidates}'.

    Returns:
      Dict of parameter names to their values mapped from this DNA.

    Raises:
      ValueError: If the DNA is not bound with a DNASpec.
    """
    value_type = 'choice_and_literal' if use_literal_values else 'choice'
    return cast(dict[str, str], self.to_dict(value_type=value_type))

from_parameters classmethod

from_parameters(
    parameters: dict[str, Any],
    dna_spec: DNASpec,
    use_literal_values: bool = False,
) -> DNA

Create DNA from parameters based on DNASpec.

Deprecated: use from_dict instead.

Parameters:

Name	Type	Description	Default
parameters	dict[str, Any]	A 1-depth dict of parameter names to parameter values.	required
dna_spec	DNASpec	DNASpec to interpret the parameters.	required
use_literal_values	bool	If True, integer decisions are interpreted as literal values of the corresponding choice rather than candidate indices. String decisions are always accepted as either literal values or '<index>/<num_candidates>' forms.	False

Returns:

Type	Description
DNA	DNA instance bound with the DNASpec.

Raises:

Type	Description
ValueError	If parameters are not aligned with DNA spec.

Source code in pygx/geno/_base.py

@classmethod
def from_parameters(
    cls,
    parameters: dict[str, Any],
    dna_spec: DNASpec,
    use_literal_values: bool = False,
) -> 'DNA':
    """Create DNA from parameters based on DNASpec.

    Deprecated: use `from_dict` instead.

    Args:
      parameters: A 1-depth dict of parameter names to parameter values.
      dna_spec: DNASpec to interpret the parameters.
      use_literal_values: If True, integer decisions are interpreted as
        literal values of the corresponding choice rather than candidate
        indices. String decisions are always accepted as either literal
        values or ``'<index>/<num_candidates>'`` forms.

    Returns:
      DNA instance bound with the DNASpec.

    Raises:
      ValueError: If parameters are not aligned with DNA spec.
    """
    return cls.from_dict(
        parameters, dna_spec, use_ints_as_literals=use_literal_values
    )

AttributeDict

Bases: dict

A dictionary that allows attribute access.

ConditionalKey

ConditionalKey(index: int, num_choices: int)

Key used in pygx.KeyPath to represent conditional element.

A conditional key renders as =<index>/<num_choices>. For example, a[=1/2].b identifies b under choice a when candidate 1 (out of 2) is chosen, and a[0][=0/3].b identifies b under subchoice a[0] of a multi-choice when its candidate 0 (out of 3) is chosen.

Source code in pygx/geno/_base.py

def __init__(self, index: int, num_choices: int):
    self._index = index
    self._num_choices = num_choices

index property

index: int

Return selected index of current condition.

num_choices property

num_choices: int

Returns number of choices of current condition.

DecisionPoint

DecisionPoint(
    *,
    allow_partial: bool = False,
    sealed: bool | None = None,
    root_path: KeyPath | None = None,
    explicit_init: bool = False,
    **kwargs: Any
)

Bases: DNASpec

Base class for decision points.

Child classes:

• pygx.geno.Choices
• pygx.geno.Float
• pygx.geno.CustomDecisionPoint

Source code in pygx/symbolic/_object.py

@_filter_typing_traceback_on_raise
def __init__(
    self,
    *,
    allow_partial: bool = False,
    sealed: bool | None = None,
    root_path: topology.KeyPath | None = None,
    explicit_init: bool = False,
    **kwargs: Any,
):
    """Create an Object instance.

    ``pg.Object`` synthesizes a keyword-only ``__init__``. Subclasses
    that need positional arguments must override ``__init__``
    explicitly and translate to keyword arguments before forwarding
    to ``super().__init__(**kwargs)``.

    Args:
      allow_partial: If True, the object can be partial.
      sealed: If True, seal the object from future modification (unless under
        a `pg.as_sealed(False)` context manager). If False, treat the object as
        unsealed. If None, it's determined by the class's ``frozen`` option.
      root_path: The symbolic path for current object. By default it's None,
        which indicates that newly constructed object does not have a parent.
      explicit_init: Should set to `True` when `__init__` is called via
        `pg.Object.__init__` instead of `super().__init__`.
      **kwargs: key/value arguments that align with the schema. All required
        keys in the schema must be specified, and values should be acceptable
        according to their value spec.

    Raises:
      TypeError: When a required field is missing, a value has an
        unacceptable type, or an unknown keyword argument is given.
      ValueError: When a value violates its value spec's constraints
        (e.g. out of range).
    """
    # Placeholder for Google-internal usage instrumentation.

    cls = self.__class__
    # The ever-instantiated latch `apply_schema`'s post-instance guard
    # reads (#432: `update_schema` is only legal before instances exist).
    # Own-`__dict__`, latched on the construction ATTEMPT — mirroring the
    # native core, whose `__native_ctor_meta__` (the equivalent marker) is
    # created on the first instance op. One dict read per construct.
    meta = cls.__sym_meta__
    if not meta.instantiated:
        meta.instantiated = True
    if sealed is None:
        sealed = cls.__sym_options__.frozen

    if not isinstance(allow_partial, bool):
        raise TypeError(
            f"Expect bool type for argument 'allow_partial' in "
            f'symbolic.Object.__init__ but encountered {allow_partial}.'
        )

    # Fast path: const-keyed schema.
    if cls._sym_init_fields is not None and self._init_fast_path(
        kwargs,
        allow_partial,
        sealed,
        root_path,
        explicit_init,
    ):
        return

    # Slow path: handles varargs and schemas with non-const keys.

    # Model before-hook (#516) — the fast path was not taken
    # (`_sym_init_fields is None`), so the hook has not run yet.
    if cls._sym_preinit_overridden:
        kwargs = _apply_preinit(cls, kwargs)

    # We delay the seal attempt until members are all set.
    super().__init__(
        allow_partial=allow_partial,
        accessor_writable=cls.__sym_options__.attr_write,
        sealed=sealed,
        root_path=root_path,
        init_super=not explicit_init,
    )

    # Fill field_args and init_args from **kwargs.
    _, unmatched_keys = cls.__schema__.resolve(list(kwargs.keys()))
    # Fields opted out of `__init__` via `enable_init=False` resolve
    # against the schema but must still be rejected as kwargs.
    get_field = cls.__schema__.get_field
    unmatched_keys = list(unmatched_keys) + [
        k
        for k in kwargs
        if (f := get_field(k)) is not None and not f.enable_init
    ]
    if unmatched_keys:
        _screen_unexpected_init_keys(cls, kwargs, unmatched_keys)

    # Declared aliases are RESERVED wire spellings (#517, owner ruling):
    # an open (extra) schema must not accept an extra kwarg equal to a
    # field's alias — the wire would become ambiguous. (Const-keyed
    # schemas never reach here with an alias-spelled kwarg; their
    # unknown-key screen already raised — or, under `extra='ignore'`,
    # raised for alias keys before dropping the rest.)
    if cls._sym_alias_maps is not None:
        alias_to_name = cls._sym_alias_maps[0]
        for k in kwargs:
            if k in alias_to_name:
                raise TypeError(
                    f'{cls.__name__}.__init__() got keyword argument '
                    f'{k!r}, which is reserved as the alias of field '
                    f'{alias_to_name[k]!r}.'
                )

    # All field values come from kwargs — `pg.Object.__init__` is
    # keyword-only.
    field_args = dict(kwargs)

    # Check missing arguments when partial binding is disallowed.
    if not base.accepts_partial(self):
        missing_args = []
        for field in self.__class__.__schema__.fields.values():
            if (
                not field.value.has_default
                and isinstance(field.key, pg_typing.ConstStrKey)
                and field.key not in field_args
            ):
                missing_args.append(str(field.key))
        if missing_args:
            arg_phrase = formatting.auto_plural(
                len(missing_args), 'argument'
            )
            keys_str = formatting.comma_delimited_str(missing_args)
            raise TypeError(
                f'{self.__class__.__name__}.__init__() missing {len(missing_args)} '
                f'required {arg_phrase}: {keys_str}.'
            )

    # NOTE(daiyip): Accessor writable is honored by `Object.__setattr__` so
    # we can always make `_sym_attributes` accessor writable. This prevents
    # a child object's attribute access from being changed when it's
    # attached to a parent whose symbolic attributes are not writable.
    # Per-field validation is gated by `field.enable_validation` inside
    # `Schema.apply` / `Dict._formalized_value` — so a class-wide
    # `validate=False` (resolved into each field) and per-field overrides
    # both flow through naturally here.
    vars(self)['_sym_attributes'] = pg_dict.Dict(
        field_args,  # pyright: ignore[reportArgumentType]
        value_spec=self.__class__.sym_fields,
        allow_partial=allow_partial,
        sealed=sealed,
        accessor_writable=True,
        root_path=root_path,
        as_object_attributes_container=True,
        under_topo=cls.__sym_options__.topo,
    )
    # The write-time `needs_topo` refusal (see `_init_fast_path` Phase 5):
    # the slow path formalizes inside the container, so scan its items.
    if not cls.__sym_options__.topo:
        for k, v in self._sym_attributes.sym_items():
            base.refuse_tree_walking_inferential(cls, k, v)
    self._sym_attributes.topo_setparent(self)
    # Seed `init=False` fields from their defaults before `on_sym_post_init`
    # runs so `on_sym_ready`/`on_sym_bound` overrides start from a known baseline.
    _seed_non_symbolic_fields(self, cls._non_symbolic_fields)
    # Model after-validator (#516): fires before any lifecycle hook can
    # observe the object, gated like `on_sym_ready` (concrete only).
    if cls._sym_validate_overridden:
        abstract = (
            self._allow_partial and self.sym_partial
        ) or self.sym_puresymbolic
        if not abstract:
            self.on_sym_validate()
    self.on_sym_post_init()
    self.sym_seal(sealed)

DNASpec

DNASpec(
    *,
    allow_partial: bool = False,
    sealed: bool | None = None,
    root_path: KeyPath | None = None,
    explicit_init: bool = False,
    **kwargs: Any
)

Bases: Object

Base class for DNA specifications (genotypes).

A DNASpec object describes the rules and tips for generating a DNA. It has two families of subclasses:

• pygx.geno.Space: Represents a space or sub-space, which contains a list of decision points.
• pygx.geno.DecisionPoint: Represents a concrete decision point.

Concrete decision points are the following:

• pygx.geno.Choices: Represents a single categorical choice or multiple related categorical choices. Each candidate is a sub-space.
• pygx.geno.Float: Represents a continuous float value within a range.
• pygx.geno.CustomDecisionPoint: Represents the genotype for a pygx.hyper.CustomHyper.

Every decision point carries hints as a reference for the DNA generator to consume when generating values. Hints must be serializable so they can be passed between clients and servers.

All DNASpec types also allow users to attach data via set_userdata. User data is meant to be used within the same process only, thus is not required to be serializable.

Source code in pygx/symbolic/_object.py

@_filter_typing_traceback_on_raise
def __init__(
    self,
    *,
    allow_partial: bool = False,
    sealed: bool | None = None,
    root_path: topology.KeyPath | None = None,
    explicit_init: bool = False,
    **kwargs: Any,
):
    """Create an Object instance.

    ``pg.Object`` synthesizes a keyword-only ``__init__``. Subclasses
    that need positional arguments must override ``__init__``
    explicitly and translate to keyword arguments before forwarding
    to ``super().__init__(**kwargs)``.

    Args:
      allow_partial: If True, the object can be partial.
      sealed: If True, seal the object from future modification (unless under
        a `pg.as_sealed(False)` context manager). If False, treat the object as
        unsealed. If None, it's determined by the class's ``frozen`` option.
      root_path: The symbolic path for current object. By default it's None,
        which indicates that newly constructed object does not have a parent.
      explicit_init: Should set to `True` when `__init__` is called via
        `pg.Object.__init__` instead of `super().__init__`.
      **kwargs: key/value arguments that align with the schema. All required
        keys in the schema must be specified, and values should be acceptable
        according to their value spec.

    Raises:
      TypeError: When a required field is missing, a value has an
        unacceptable type, or an unknown keyword argument is given.
      ValueError: When a value violates its value spec's constraints
        (e.g. out of range).
    """
    # Placeholder for Google-internal usage instrumentation.

    cls = self.__class__
    # The ever-instantiated latch `apply_schema`'s post-instance guard
    # reads (#432: `update_schema` is only legal before instances exist).
    # Own-`__dict__`, latched on the construction ATTEMPT — mirroring the
    # native core, whose `__native_ctor_meta__` (the equivalent marker) is
    # created on the first instance op. One dict read per construct.
    meta = cls.__sym_meta__
    if not meta.instantiated:
        meta.instantiated = True
    if sealed is None:
        sealed = cls.__sym_options__.frozen

    if not isinstance(allow_partial, bool):
        raise TypeError(
            f"Expect bool type for argument 'allow_partial' in "
            f'symbolic.Object.__init__ but encountered {allow_partial}.'
        )

    # Fast path: const-keyed schema.
    if cls._sym_init_fields is not None and self._init_fast_path(
        kwargs,
        allow_partial,
        sealed,
        root_path,
        explicit_init,
    ):
        return

    # Slow path: handles varargs and schemas with non-const keys.

    # Model before-hook (#516) — the fast path was not taken
    # (`_sym_init_fields is None`), so the hook has not run yet.
    if cls._sym_preinit_overridden:
        kwargs = _apply_preinit(cls, kwargs)

    # We delay the seal attempt until members are all set.
    super().__init__(
        allow_partial=allow_partial,
        accessor_writable=cls.__sym_options__.attr_write,
        sealed=sealed,
        root_path=root_path,
        init_super=not explicit_init,
    )

    # Fill field_args and init_args from **kwargs.
    _, unmatched_keys = cls.__schema__.resolve(list(kwargs.keys()))
    # Fields opted out of `__init__` via `enable_init=False` resolve
    # against the schema but must still be rejected as kwargs.
    get_field = cls.__schema__.get_field
    unmatched_keys = list(unmatched_keys) + [
        k
        for k in kwargs
        if (f := get_field(k)) is not None and not f.enable_init
    ]
    if unmatched_keys:
        _screen_unexpected_init_keys(cls, kwargs, unmatched_keys)

    # Declared aliases are RESERVED wire spellings (#517, owner ruling):
    # an open (extra) schema must not accept an extra kwarg equal to a
    # field's alias — the wire would become ambiguous. (Const-keyed
    # schemas never reach here with an alias-spelled kwarg; their
    # unknown-key screen already raised — or, under `extra='ignore'`,
    # raised for alias keys before dropping the rest.)
    if cls._sym_alias_maps is not None:
        alias_to_name = cls._sym_alias_maps[0]
        for k in kwargs:
            if k in alias_to_name:
                raise TypeError(
                    f'{cls.__name__}.__init__() got keyword argument '
                    f'{k!r}, which is reserved as the alias of field '
                    f'{alias_to_name[k]!r}.'
                )

    # All field values come from kwargs — `pg.Object.__init__` is
    # keyword-only.
    field_args = dict(kwargs)

    # Check missing arguments when partial binding is disallowed.
    if not base.accepts_partial(self):
        missing_args = []
        for field in self.__class__.__schema__.fields.values():
            if (
                not field.value.has_default
                and isinstance(field.key, pg_typing.ConstStrKey)
                and field.key not in field_args
            ):
                missing_args.append(str(field.key))
        if missing_args:
            arg_phrase = formatting.auto_plural(
                len(missing_args), 'argument'
            )
            keys_str = formatting.comma_delimited_str(missing_args)
            raise TypeError(
                f'{self.__class__.__name__}.__init__() missing {len(missing_args)} '
                f'required {arg_phrase}: {keys_str}.'
            )

    # NOTE(daiyip): Accessor writable is honored by `Object.__setattr__` so
    # we can always make `_sym_attributes` accessor writable. This prevents
    # a child object's attribute access from being changed when it's
    # attached to a parent whose symbolic attributes are not writable.
    # Per-field validation is gated by `field.enable_validation` inside
    # `Schema.apply` / `Dict._formalized_value` — so a class-wide
    # `validate=False` (resolved into each field) and per-field overrides
    # both flow through naturally here.
    vars(self)['_sym_attributes'] = pg_dict.Dict(
        field_args,  # pyright: ignore[reportArgumentType]
        value_spec=self.__class__.sym_fields,
        allow_partial=allow_partial,
        sealed=sealed,
        accessor_writable=True,
        root_path=root_path,
        as_object_attributes_container=True,
        under_topo=cls.__sym_options__.topo,
    )
    # The write-time `needs_topo` refusal (see `_init_fast_path` Phase 5):
    # the slow path formalizes inside the container, so scan its items.
    if not cls.__sym_options__.topo:
        for k, v in self._sym_attributes.sym_items():
            base.refuse_tree_walking_inferential(cls, k, v)
    self._sym_attributes.topo_setparent(self)
    # Seed `init=False` fields from their defaults before `on_sym_post_init`
    # runs so `on_sym_ready`/`on_sym_bound` overrides start from a known baseline.
    _seed_non_symbolic_fields(self, cls._non_symbolic_fields)
    # Model after-validator (#516): fires before any lifecycle hook can
    # observe the object, gated like `on_sym_ready` (concrete only).
    if cls._sym_validate_overridden:
        abstract = (
            self._allow_partial and self.sym_partial
        ) or self.sym_puresymbolic
        if not abstract:
            self.on_sym_validate()
    self.on_sym_post_init()
    self.sym_seal(sealed)

is_space abstractmethod property

is_space: bool

Returns True if current node is a sub-space.

is_categorical abstractmethod property

is_categorical: bool

Returns True if current node is a categorical choice.

is_subchoice abstractmethod property

is_subchoice: bool

Returns True if current node is a subchoice of a multi-choice.

is_numerical abstractmethod property

is_numerical: bool

Returns True if current node is numerical decision.

is_custom_decision_point abstractmethod property

is_custom_decision_point: bool

Returns True if current node is a custom decision point.

decision_points abstractmethod property

decision_points: list[DecisionPoint]

Returns all decision points in their declaration order.

decision_ids property

decision_ids: list[KeyPath]

Returns decision IDs.

named_decision_points property

named_decision_points: dict[str, Union[DecisionPoint, list[DecisionPoint]]]

Returns all named decision points in their declaration order.

space_size abstractmethod property

space_size: int

Returns the size of the search space, or -1 if infinite.

parent_spec property

parent_spec: Optional[DNASpec]

Returns parent spec. None if spec is root.

parent_choice property

parent_choice: Optional[DecisionPoint]

Returns the parent choice of current space.

id property

id: KeyPath

Returns a path of locations from the root as the ID for current node.

The ID is the canonical identifier of a decision point within its search space. Locations under a chosen candidate are qualified by a conditional key (see pg.geno.ConditionalKey), and subchoices of a multi-choice are indexed by their position. For example, given:

spec = pg.geno.space([
  pg.geno.oneof([
    pg.geno.constant(),
    pg.geno.space([pg.geno.floatv(0.1, 1.0, location='lr')]),
  ], location='model'),
  pg.geno.manyof(
    2, [pg.geno.constant(), pg.geno.constant(), pg.geno.constant()],
    location='ops'),
])

the decision points have IDs model, model[=1/2].lr (the float is active only when candidate 1 of 2 is chosen), ops[0] and ops[1] (the two subchoices of the multi-choice).

userdata property

userdata: AttributeDict

Gets user data.

on_sym_bound

on_sym_bound()

Event that is triggered when object is modified.

Source code in pygx/geno/_base.py

def on_sym_bound(self):
    """Event that is triggered when object is modified."""
    super().on_sym_bound()
    self._id = None
    self._named_decision_points_cache = None
    self._decision_point_by_id_cache = None
    self._userdata = AttributeDict()

on_topo_path_change

on_topo_path_change(old_path, new_path)

Event that is triggered when path changes.

Source code in pygx/geno/_base.py

def on_topo_path_change(self, old_path, new_path):
    """Event that is triggered when path changes."""
    super().on_topo_path_change(old_path, new_path)
    # We invalidate the ID cache and decision_point_by_id cache
    # when the ancestor hierarchy changes, which will force the ID and
    # the cache to be recomputed upon usage.
    self._id = None
    self._decision_point_by_id_cache = None

validate abstractmethod

validate(dna: DNA) -> None

Validate whether a DNA value conforms to this spec.

Source code in pygx/geno/_base.py

@abc.abstractmethod
def validate(self, dna: 'DNA') -> None:
    """Validate whether a DNA value conforms to this spec."""

first_dna

first_dna(attach_spec: bool = True) -> DNA

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

Parameters:

Name	Type	Description	Default
attach_spec	bool	If True, current spec will be attached to the returned DNA.	True

Returns:

Type	Description
DNA	The first DNA in enumeration order.

Source code in pygx/geno/_base.py

def first_dna(self, attach_spec: bool = True) -> 'DNA':
    """Returns the first DNA in the space represented by this spec.

    Args:
      attach_spec: If True, current spec will be attached to the returned
        DNA.

    Returns:
      The first DNA in enumeration order.
    """
    dna = self.next_dna(None, attach_spec)
    assert dna is not None
    return dna

next_dna

next_dna(dna: Optional[DNA] = None, attach_spec: bool = True) -> Optional[DNA]

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

Parameters:

Name	Type	Description	Default
dna	Optional[DNA]	The DNA whose next will be returned. If None, next_dna will return the first DNA.	None
attach_spec	bool	If True, current spec will be attached to the returned DNA.	True

Returns:

Type	Description
Optional[DNA]	The next DNA or None if there is no next DNA.

Raises:

Type	Description
NotImplementedError	The (sub-)space is not enumerable - e.g. it contains a Float or a CustomDecisionPoint without a next_dna_fn.

Source code in pygx/geno/_base.py

def next_dna(
    self, dna: Optional['DNA'] = None, attach_spec: bool = True
) -> Optional['DNA']:
    """Returns the next DNA in the space represented by this spec.

    Args:
      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.

    Raises:
      NotImplementedError: The (sub-)space is not enumerable - e.g. it
        contains a `Float` or a `CustomDecisionPoint` without a
        `next_dna_fn`.
    """
    dna = self._next_dna(dna)
    if attach_spec and dna is not None:
        dna.use_spec(self)
    return dna

random_dna

random_dna(
    random_generator: ModuleType | Random | None = None,
    attach_spec: bool = True,
    previous_dna: Optional[DNA] = None,
) -> DNA

Returns a random DNA based on current spec.

Parameters:

Name	Type	Description	Default
random_generator	ModuleType | Random | None	An optional Random object. If None, the global random module will be used.	None
attach_spec	bool	If True, current spec will be attached to the returned DNA.	True
previous_dna	Optional[DNA]	An optional DNA representing previous DNA. This field might be useful for generating stateful random DNAs.	None

Returns:

Type	Description
DNA	A random DNA based on current spec.

Source code in pygx/geno/_base.py

def random_dna(
    self,
    random_generator: types.ModuleType | random.Random | None = None,
    attach_spec: bool = True,
    previous_dna: Optional['DNA'] = None,
) -> 'DNA':
    """Returns a random DNA based on current spec.

    Args:
      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.
    """
    random_generator = random_generator or random
    dna = self._random_dna(random_generator, previous_dna)
    if attach_spec:
        dna.use_spec(self)
    return dna

iter_dna

iter_dna(dna: Optional[DNA] = None, attach_spec: bool = True) -> Iterator[DNA]

Iterate the DNA in the space represented by this spec.

Parameters:

Name	Type	Description	Default
dna	Optional[DNA]	An optional DNA as the start point (exclusive) for iteration.	None
attach_spec	bool	If True, the DNASpec will be attached to the DNA returned.	True

Yields:

Type	Description
DNA	The next DNA according to the spec.

Source code in pygx/geno/_base.py

def iter_dna(
    self, dna: Optional['DNA'] = None, attach_spec: bool = True
) -> Iterator['DNA']:
    """Iterate the DNA in the space represented by this spec.

    Args:
      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.
    """
    while True:
        dna = self.next_dna(dna, attach_spec)
        if dna is None:
            break
        yield dna

get

get(
    name_or_id: KeyPath | str, default: Any = None
) -> Union[DecisionPoint, list[DecisionPoint]]

Get decision point(s) by name or ID, with a default for misses.

Names are looked up first, then IDs. The subchoices of a multi-choice share the parent's ID, so an ID lookup on a multi-choice returns a list of decision points.

Example:

spec = pg.geno.space([
  pg.geno.oneof(
    [pg.geno.constant(), pg.geno.constant()],
    location='x', name='x_choice'),
])
assert spec.get('x_choice') is spec.get('x')
assert spec.get('nope') is None

Parameters:

Name	Type	Description	Default
name_or_id	KeyPath | str	The name or ID of the decision point(s) to look up.	required
default	Any	Value to return when no decision point matches.	None

Returns:

Type	Description
Union[DecisionPoint, list[DecisionPoint]]	The matching decision point, a list of decision points (for the
Union[DecisionPoint, list[DecisionPoint]]	subchoices of a multi-choice), or default if not found.

Source code in pygx/geno/_base.py

def get(
    self, name_or_id: topology.KeyPath | str, default: Any = None
) -> Union['DecisionPoint', list['DecisionPoint']]:
    """Get decision point(s) by name or ID, with a default for misses.

    Names are looked up first, then IDs. The subchoices of a multi-choice
    share the parent's ID, so an ID lookup on a multi-choice returns a
    list of decision points.

    **Example:**

    ```python
    spec = pg.geno.space([
      pg.geno.oneof(
        [pg.geno.constant(), pg.geno.constant()],
        location='x', name='x_choice'),
    ])
    assert spec.get('x_choice') is spec.get('x')
    assert spec.get('nope') is None
    ```

    Args:
      name_or_id: The name or ID of the decision point(s) to look up.
      default: Value to return when no decision point matches.

    Returns:
      The matching decision point, a list of decision points (for the
      subchoices of a multi-choice), or `default` if not found.
    """
    try:
        return self[name_or_id]
    except KeyError:
        return default

set_userdata

set_userdata(key: str, value: Any) -> None

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.

Parameters:

Name	Type	Description	Default
key	str	Key of the user data.	required
value	Any	Value of the user data.	required

Source code in pygx/geno/_base.py

def set_userdata(self, key: str, value: Any) -> None:
    """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.

    Args:
      key: Key of the user data.
      value: Value of the user data.
    """
    self._userdata[key] = value

from_json classmethod

from_json(json_value, *args, **kwargs) -> Object

Override from_json for backward compatibility with serialized data.

Source code in pygx/geno/_base.py

@classmethod
def from_json(cls, json_value, *args, **kwargs) -> symbolic.Object:
    """Override from_json for backward compatibility with serialized data."""
    assert isinstance(json_value, dict)
    json_value.pop('userdata', None)
    return super().from_json(json_value, *args, **kwargs)

Choices

Choices(num_choices: int = 1, *, candidates: list[Space], **kwargs)

Bases: DecisionPoint

Represents a single or multiple choices from a list of candidates.

Example:

# Create a single choice with a nested subspace for candidate 2 (0-based).
pg.geno.oneof([
    pg.geno.constant(),
    pg.geno.constant(),
    pg.geno.space([
        pg.geno.floatv(0.1, 1.0),
        pg.geno.manyof(2, [
            pg.geno.constant(),
            pg.geno.constant(),
            pg.geno.constant()
        ])
    ])
])

See also: pygx.geno.oneof, pygx.geno.manyof.

Source code in pygx/geno/_categorical.py

def __init__(
    self,
    num_choices: int = 1,
    *,
    candidates: list['Space'],
    **kwargs,
):
    super().__init__(
        **dict(num_choices=num_choices, candidates=candidates),
        **kwargs,
    )

choice_specs property

choice_specs: list[Choices]

Returns all choice specs.

is_categorical property

is_categorical: bool

Returns True if current node is a categorical choice.

is_subchoice property

is_subchoice: bool

Returns if current choice is a subchoice of a multi-choice.

is_numerical property

is_numerical: bool

Returns True if current node is numerical decision.

is_custom_decision_point property

is_custom_decision_point: bool

Returns True if current node is a custom decision point.

decision_points property

decision_points: list[DecisionPoint]

Returns all decision points in their declaration order.

Returns:

Type	Description
list[DecisionPoint]	All decision points in current space. For multi-choices, the sub-choice
list[DecisionPoint]	objects will be returned. Users can call spec.parent_spec on a
list[DecisionPoint]	sub-choice to access the parent multi-choice node.

space_size property

space_size: int

Returns the size of the search space, or -1 if infinite.

subchoice

subchoice(index: int) -> Choices

Returns spec for choice i.

Source code in pygx/geno/_categorical.py

def subchoice(self, index: int) -> 'Choices':
    """Returns spec for choice i."""
    if self.is_subchoice:
        raise ValueError(
            f"'subchoice' should not be called on a subchoice of a "
            f'multi-choice. Encountered: {self!r}.'
        )
    if self.num_choices == 1:
        return self
    assert self._subchoice_specs is not None
    return self._subchoice_specs[index]

format_candidate

format_candidate(
    index: int, display_format: str = "choice_and_literal"
) -> str | int | float

Get a formatted candidate value by index.

Parameters:

Name	Type	Description	Default
index	int	The index of the candidate to format.	required
display_format	str	One of 'choice', 'literal' and 'choice_and_literal' as the output format for human consumption.	'choice_and_literal'

Returns:

Type	Description
str | int | float	A int, float or string that represent the candidate based on the display format.

Source code in pygx/geno/_categorical.py

def format_candidate(
    self, index: int, display_format: str = 'choice_and_literal'
) -> str | int | float:
    """Get a formatted candidate value by index.

    Args:
      index: The index of the candidate to format.
      display_format: One of 'choice', 'literal' and 'choice_and_literal' as
        the output format for human consumption.

    Returns:
      A int, float or string that represent the candidate based on the
        display format.
    """
    if display_format not in ['choice', 'literal', 'choice_and_literal']:
        raise ValueError(
            f"`display_format` must be either 'choice', 'literal', or "
            f"'choice_and_literal'. Encountered: {display_format!r}."
        )
    if self.literal_values:
        if display_format == 'literal':
            return self.literal_values[index]
        elif display_format == 'choice_and_literal':
            return f'{index}/{len(self.candidates)} ({self.literal_values[index]})'
    return f'{index}/{len(self.candidates)}'

candidate_index

candidate_index(choice_value: str | int | float) -> int

Returns the candidate index of a choice value.

Parameters:

Name	Type	Description	Default
choice_value	str | int | float	Choice value can be: a (integer, float or string) as a candidate's literal value, or a text in the format "/" or a text in the format "/ ()".	required

Returns:

Type	Description
int	The index of chosen candidate.

Raises:

Type	Description
ValueError	choice_value is not a valid index or it does not match any candidate's literal value.

Source code in pygx/geno/_categorical.py

def candidate_index(self, choice_value: str | int | float) -> int:
    """Returns the candidate index of a choice value.

    Args:
      choice_value: Choice value can be:
        a (integer, float or string) as a candidate's literal value,
        or a text in the format "<index>/<num_candidates>"
        or a text in the format "<index>/<num_candidates> (<literal>)".

    Returns:
      The index of chosen candidate.

    Raises:
      ValueError: `choice_value` is not a valid index or it does not match
        any candidate's literal value.
    """

    def _index_from_literal(value: str | int | float) -> int:
        index = self._literal_index.get(value)
        if index is None:
            raise ValueError(
                f'There is no candidate in {self!r} with literal value {value!r}.'
            )
        return index

    index = None
    literal = None
    num_candidates = len(self.candidates)
    if isinstance(choice_value, str):
        r = _CHOICE_AND_LITERAL_REGEX.match(choice_value)
        if r:
            index = int(r.group(1))
            num_candidates = int(r.group(2))
            literal = r.group(3)
        else:
            r = _CHOICE_REGEX.match(choice_value)
            if r:
                index = int(r.group(1))
                num_candidates = int(r.group(2))
            else:
                index = _index_from_literal(choice_value)
    elif isinstance(choice_value, (int, float)):
        index = _index_from_literal(choice_value)
    else:
        raise ValueError(
            f"The value for Choice '{self.id}' should be either an integer, "
            f'a float or a string. Encountered: {choice_value!r}.'
        )
    if index < -len(self.candidates) or index >= len(self.candidates):
        raise ValueError(
            f"Candidate index out of range at choice '{self.name or self.id}'. "
            f'Index={index}, Number of candidates={len(self.candidates)}.'
        )
    if num_candidates != len(self.candidates):
        raise ValueError(
            f'Number of candidates ({num_candidates}) for Choice '
            f"'{self.name or self.id}' does not match with "
            f'DNASpec ({len(self.candidates)}).'
        )
    if literal is not None and (
        not self.literal_values
        or literal != str(self.literal_values[index])
    ):
        raise ValueError(
            f'The literal value from the input ({literal!r}) does not match '
            f'with the literal value ({self.literal_values[index]!r}) from the '  # pyright: ignore[reportOptionalSubscript]
            f'chosen candidate (index={index}).'
        )
    return index

validate

validate(dna: DNA) -> None

Validate whether a DNA value conforms to this spec.

Source code in pygx/geno/_categorical.py

def validate(self, dna: DNA) -> None:
    """Validate whether a DNA value conforms to this spec."""
    if self.num_choices == 1:
        # For single choice, choice is decoded from dna.value.
        # children should be decoded by chosen candidate.
        if dna.value is None and dna.children:
            raise ValueError(
                f'Expect an integer for a single choice, but encountered a list '
                f'({dna.to_numbers(flatten=False)}). '
                f'Location: {self.location.path}.'
            )
        if not isinstance(dna.value, int):
            raise ValueError(
                f'Expect an integer for a single choice, but encountered: '
                f'{dna.value!r}, Location: {self.location.path}.'
            )
        if dna.value >= len(self.candidates):
            raise ValueError(
                f'Choice out of range. Value: {dna.value}, '
                f'Candidates: {len(self.candidates)}, '
                f'Location: {self.location.path}.'
            )
        chosen = self.candidates[dna.value]
        if chosen.is_constant and dna.children:
            raise ValueError(
                f'Child DNA ({dna.children!r}) provided while there is no child '
                f'decision point.'
            )
        elif not chosen.is_constant and not dna.children:
            raise ValueError(
                f'No child DNA provided for child space {chosen!r}.'
            )
        chosen.validate(DNA(None, dna.children))
    else:
        # For multiple choices, choice is encoded in DNA.children.
        # dna.value could be None (Choices as the only encoder in root template)
        # or int (parent choice).
        if len(dna.children) != self.num_choices:
            raise ValueError(
                f'Number of DNA child values does not match the number of choices. '
                f'Child values: {dna.children!r}, Choices: {self.num_choices}, '
                f'Location: {self.location.path}.'
            )
        if self.distinct or self.sorted:
            sub_dna_values = [s.value for s in dna]
            if self.distinct and len(set(sub_dna_values)) != len(
                dna.children
            ):
                raise ValueError(
                    f'DNA child values should be distinct. '
                    f'Encountered: {sub_dna_values}, Location: {self.location.path}.'
                )
            if self.sorted and sorted(sub_dna_values) != sub_dna_values:
                raise ValueError(
                    f'DNA child values should be sorted. '
                    f'Encountered: {sub_dna_values}, Location: {self.location.path}.'
                )
        for i, sub_dna in enumerate(dna):
            sub_location = topology.KeyPath(i, self.location)
            if not isinstance(sub_dna.value, int):
                raise ValueError(
                    f'Choice value should be int. Encountered: {sub_dna.value}, '
                    f'Location: {sub_location.path}.'
                )
            if sub_dna.value >= len(self.candidates):
                raise ValueError(
                    f'Choice out of range. Value: {sub_dna.value}, '
                    f'Candidates: {len(self.candidates)}, '
                    f'Location: {sub_location.path}.'
                )
            self.candidates[sub_dna.value].validate(
                DNA(None, sub_dna.children)
            )

format

format(
    compact: bool = True,
    verbose: bool = True,
    root_indent: int = 0,
    show_id: bool = True,
    **kwargs
)

Format this object.

Source code in pygx/geno/_categorical.py

def format(
    self,
    compact: bool = True,
    verbose: bool = True,
    root_indent: int = 0,
    show_id: bool = True,
    **kwargs,
):
    """Format this object."""
    if not compact:
        return super().format(compact, verbose, root_indent, **kwargs)

    def _indent(text, indent):
        return ' ' * 2 * indent + text

    s = [f'Choices(num_choices={self.num_choices}, [\n']
    if not self.literal_values:
        for i, candidate in enumerate(self.candidates):
            candidate_str = candidate.format(
                compact, verbose, root_indent + 1, **kwargs
            )
            s.append(_indent(f'({i}): {candidate_str}\n', root_indent + 1))
    else:
        assert len(self.literal_values) == len(self.candidates)
        for i, (candidate, literal_value) in enumerate(
            zip(self.candidates, self.literal_values)
        ):
            if not candidate.is_constant:
                value_str = candidate.format(
                    compact, verbose, root_indent + 1, **kwargs
                )
            else:
                value_str = literal_value
            s.append(_indent(f'({i}): {value_str}\n', root_indent + 1))
    s.append(_indent(']', root_indent))
    kvlist: list[tuple[str, Any, Any]]
    if show_id:
        kvlist = [('id', str(self.id), "''")]
    else:
        kvlist = []
    # `compact=True`: the properties join INLINE after the candidate
    # list's closing bracket. The former `compact=False` made
    # `kvlist_str` prefix each item with `root_indent` padding, which
    # rendered as `],   distinct=False)` with depth-scaled spaces (#783).
    additionl_properties = formatting.kvlist_str(
        kvlist
        + [
            ('name', self.name, None),
            ('distinct', self.distinct, True),
            ('sorted', self.sorted, False),
            ('hints', self.hints, None),
            ('subchoice_index', self.subchoice_index, None),
        ],
        compact=True,
        root_indent=root_indent,
    )
    if additionl_properties:
        s.append(', ')
        s.append(additionl_properties)
    s.append(')')
    return ''.join(s)

CustomDecisionPoint

CustomDecisionPoint(
    *,
    allow_partial: bool = False,
    sealed: bool | None = None,
    root_path: KeyPath | None = None,
    explicit_init: bool = False,
    **kwargs: Any
)

Bases: DecisionPoint

Represents a user-defined decision point.

It is the genotype for pygx.hyper.CustomHyper. Its DNA value is a string whose encoding is defined by the user.

Example:

decision_point = pg.geno.custom()

See also: pygx.geno.custom.

Source code in pygx/symbolic/_object.py

@_filter_typing_traceback_on_raise
def __init__(
    self,
    *,
    allow_partial: bool = False,
    sealed: bool | None = None,
    root_path: topology.KeyPath | None = None,
    explicit_init: bool = False,
    **kwargs: Any,
):
    """Create an Object instance.

    ``pg.Object`` synthesizes a keyword-only ``__init__``. Subclasses
    that need positional arguments must override ``__init__``
    explicitly and translate to keyword arguments before forwarding
    to ``super().__init__(**kwargs)``.

    Args:
      allow_partial: If True, the object can be partial.
      sealed: If True, seal the object from future modification (unless under
        a `pg.as_sealed(False)` context manager). If False, treat the object as
        unsealed. If None, it's determined by the class's ``frozen`` option.
      root_path: The symbolic path for current object. By default it's None,
        which indicates that newly constructed object does not have a parent.
      explicit_init: Should set to `True` when `__init__` is called via
        `pg.Object.__init__` instead of `super().__init__`.
      **kwargs: key/value arguments that align with the schema. All required
        keys in the schema must be specified, and values should be acceptable
        according to their value spec.

    Raises:
      TypeError: When a required field is missing, a value has an
        unacceptable type, or an unknown keyword argument is given.
      ValueError: When a value violates its value spec's constraints
        (e.g. out of range).
    """
    # Placeholder for Google-internal usage instrumentation.

    cls = self.__class__
    # The ever-instantiated latch `apply_schema`'s post-instance guard
    # reads (#432: `update_schema` is only legal before instances exist).
    # Own-`__dict__`, latched on the construction ATTEMPT — mirroring the
    # native core, whose `__native_ctor_meta__` (the equivalent marker) is
    # created on the first instance op. One dict read per construct.
    meta = cls.__sym_meta__
    if not meta.instantiated:
        meta.instantiated = True
    if sealed is None:
        sealed = cls.__sym_options__.frozen

    if not isinstance(allow_partial, bool):
        raise TypeError(
            f"Expect bool type for argument 'allow_partial' in "
            f'symbolic.Object.__init__ but encountered {allow_partial}.'
        )

    # Fast path: const-keyed schema.
    if cls._sym_init_fields is not None and self._init_fast_path(
        kwargs,
        allow_partial,
        sealed,
        root_path,
        explicit_init,
    ):
        return

    # Slow path: handles varargs and schemas with non-const keys.

    # Model before-hook (#516) — the fast path was not taken
    # (`_sym_init_fields is None`), so the hook has not run yet.
    if cls._sym_preinit_overridden:
        kwargs = _apply_preinit(cls, kwargs)

    # We delay the seal attempt until members are all set.
    super().__init__(
        allow_partial=allow_partial,
        accessor_writable=cls.__sym_options__.attr_write,
        sealed=sealed,
        root_path=root_path,
        init_super=not explicit_init,
    )

    # Fill field_args and init_args from **kwargs.
    _, unmatched_keys = cls.__schema__.resolve(list(kwargs.keys()))
    # Fields opted out of `__init__` via `enable_init=False` resolve
    # against the schema but must still be rejected as kwargs.
    get_field = cls.__schema__.get_field
    unmatched_keys = list(unmatched_keys) + [
        k
        for k in kwargs
        if (f := get_field(k)) is not None and not f.enable_init
    ]
    if unmatched_keys:
        _screen_unexpected_init_keys(cls, kwargs, unmatched_keys)

    # Declared aliases are RESERVED wire spellings (#517, owner ruling):
    # an open (extra) schema must not accept an extra kwarg equal to a
    # field's alias — the wire would become ambiguous. (Const-keyed
    # schemas never reach here with an alias-spelled kwarg; their
    # unknown-key screen already raised — or, under `extra='ignore'`,
    # raised for alias keys before dropping the rest.)
    if cls._sym_alias_maps is not None:
        alias_to_name = cls._sym_alias_maps[0]
        for k in kwargs:
            if k in alias_to_name:
                raise TypeError(
                    f'{cls.__name__}.__init__() got keyword argument '
                    f'{k!r}, which is reserved as the alias of field '
                    f'{alias_to_name[k]!r}.'
                )

    # All field values come from kwargs — `pg.Object.__init__` is
    # keyword-only.
    field_args = dict(kwargs)

    # Check missing arguments when partial binding is disallowed.
    if not base.accepts_partial(self):
        missing_args = []
        for field in self.__class__.__schema__.fields.values():
            if (
                not field.value.has_default
                and isinstance(field.key, pg_typing.ConstStrKey)
                and field.key not in field_args
            ):
                missing_args.append(str(field.key))
        if missing_args:
            arg_phrase = formatting.auto_plural(
                len(missing_args), 'argument'
            )
            keys_str = formatting.comma_delimited_str(missing_args)
            raise TypeError(
                f'{self.__class__.__name__}.__init__() missing {len(missing_args)} '
                f'required {arg_phrase}: {keys_str}.'
            )

    # NOTE(daiyip): Accessor writable is honored by `Object.__setattr__` so
    # we can always make `_sym_attributes` accessor writable. This prevents
    # a child object's attribute access from being changed when it's
    # attached to a parent whose symbolic attributes are not writable.
    # Per-field validation is gated by `field.enable_validation` inside
    # `Schema.apply` / `Dict._formalized_value` — so a class-wide
    # `validate=False` (resolved into each field) and per-field overrides
    # both flow through naturally here.
    vars(self)['_sym_attributes'] = pg_dict.Dict(
        field_args,  # pyright: ignore[reportArgumentType]
        value_spec=self.__class__.sym_fields,
        allow_partial=allow_partial,
        sealed=sealed,
        accessor_writable=True,
        root_path=root_path,
        as_object_attributes_container=True,
        under_topo=cls.__sym_options__.topo,
    )
    # The write-time `needs_topo` refusal (see `_init_fast_path` Phase 5):
    # the slow path formalizes inside the container, so scan its items.
    if not cls.__sym_options__.topo:
        for k, v in self._sym_attributes.sym_items():
            base.refuse_tree_walking_inferential(cls, k, v)
    self._sym_attributes.topo_setparent(self)
    # Seed `init=False` fields from their defaults before `on_sym_post_init`
    # runs so `on_sym_ready`/`on_sym_bound` overrides start from a known baseline.
    _seed_non_symbolic_fields(self, cls._non_symbolic_fields)
    # Model after-validator (#516): fires before any lifecycle hook can
    # observe the object, gated like `on_sym_ready` (concrete only).
    if cls._sym_validate_overridden:
        abstract = (
            self._allow_partial and self.sym_partial
        ) or self.sym_puresymbolic
        if not abstract:
            self.on_sym_validate()
    self.on_sym_post_init()
    self.sym_seal(sealed)

is_categorical property

is_categorical: bool

Returns True if current node is a categorical choice.

is_subchoice property

is_subchoice: bool

Returns True if current node is a subchoice of a multi-choice.

is_numerical property

is_numerical: bool

Returns True if current node is numerical decision.

is_custom_decision_point property

is_custom_decision_point: bool

Returns True if current node is a custom decision point.

decision_points property

decision_points: list[DecisionPoint]

Returns all decision points in their declaration order.

space_size property

space_size: int

Returns the size of the search space, or -1 if infinite.

validate

validate(dna: DNA) -> None

Validate whether a DNA value conforms to this spec.

Source code in pygx/geno/_custom.py

def validate(self, dna: DNA) -> None:
    """Validate whether a DNA value conforms to this spec."""
    if not isinstance(dna.value, str):
        raise ValueError(
            f'CustomDecisionPoint expects string type DNA. '
            f'Encountered: {dna!r}, Location: {self.location.path}.'
        )

sym_jsonify

sym_jsonify(**kwargs: Any) -> WireValue

Overrides sym_jsonify to exclude non-serializable fields.

Source code in pygx/geno/_custom.py

def sym_jsonify(self, **kwargs: Any) -> wire.WireValue:
    """Overrides sym_jsonify to exclude non-serializable fields."""
    exclude_keys = kwargs.pop('exclude_keys', [])
    exclude_keys.extend(['random_dna_fn', 'next_dna_fn'])
    return super().sym_jsonify(exclude_keys=exclude_keys, **kwargs)

format

format(
    compact: bool = True,
    verbose: bool = True,
    root_indent: int = 0,
    show_id: bool = True,
    **kwargs
)

Format this object.

Source code in pygx/geno/_custom.py

def format(
    self,
    compact: bool = True,
    verbose: bool = True,
    root_indent: int = 0,
    show_id: bool = True,
    **kwargs,
):
    """Format this object."""
    if not compact:
        return super().format(compact, verbose, root_indent, **kwargs)
    kvlist: list[tuple[str, Any, Any]]
    if show_id:
        kvlist = [('id', str(self.id), "''")]
    else:
        kvlist = []
    details = formatting.kvlist_str(
        kvlist
        + [
            ('hyper_type', self.hyper_type, None),
            ('name', self.name, None),
            ('hints', self.hints, None),
        ]
    )
    return f'{self.__class__.__name__}({details})'

Deduping

Deduping(generator: DNAGenerator, **kwargs)

Bases: DNAGenerator

Deduping generator.

A deduping generator can be applied on another generator to dedup its proposed DNAs.

Hash function

By default, the hash function is the symbolic hash of the DNA, which returns the same hash when the decisions from the DNA are the same.

For example:

pg.geno.Deduping(pg.geno.Random())

will only generate unique DNAs. When hash_fn is specified, it allows the user to compute the hash for a DNA.

For example:

pg.geno.Deduping(pg.geno.Random(),
                 hash_fn=lambda dna: sum(dna.to_numbers()))

will dedup based on the sum of all decision values.

If no novel DNA can be obtained within max_proposal_attempts inner proposals, the generator stops (raises StopIteration).

Number of duplicates

An optional max_duplicates can be provided by the user to allow a few duplicates.

For example:

pg.geno.Deduping(pg.geno.Random(), max_duplicates=5)

Note: for inner DNAGenerators that require user feedback, duplication accounting is based on DNAs that are fed back to the DNAGenerator, not proposed ones.

Automatic reward computation

Automatic reward computation will be enabled when auto_reward_fn is provided AND when the inner generator takes feedback. It allows users to compute the reward for new duplicates (which exceed the max_duplicates limit) by aggregating rewards from previous duplicates. Such DNAs will be fed back to the DNAGenerator without client's evaluation (supported by pg.sample through the 'reward' metadata).

For example:

pg.geno.Deduping(pg.algo.evolution.regularized_evolution(),
                 auto_reward_fn=lambda rs: sum(rs) / len(rs))

Source code in pygx/geno/_deduping.py

def __init__(self, generator: DNAGenerator, **kwargs):
    super().__init__(**dict(generator=generator), **kwargs)

DNAGenerator

DNAGenerator(
    *,
    allow_partial: bool = False,
    sealed: bool | None = None,
    root_path: KeyPath | None = None,
    explicit_init: bool = False,
    **kwargs: Any
)

Bases: Object

Base class for DNA generator.

A DNA generator is an object that produces pygx.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 feedback 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 logic. 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 _replay method (which calls _feedback by default). If the user has 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 a side note, the recover method will be called by the tuning backend (pg.tuning) after setup but before propose.

Example:

class MyGenerator(pg.geno.DNAGenerator):

  def _setup(self):
    # `self.dna_spec` is available once `setup` has been called.
    self._rewards = []

  def _propose(self):
    return self.dna_spec.random_dna()

  def _feedback(self, dna, reward):
    self._rewards.append(reward)

search_space = pg.geno.space([
    pg.geno.oneof([pg.geno.constant(), pg.geno.constant()])
])
generator = MyGenerator()
generator.setup(search_space)

# Since `MyGenerator` overrides `_feedback`, iteration yields a
# (DNA, feedback) tuple; feedback-free generators yield just the DNA.
for dna, feedback in generator:
  feedback(1.0)   # Report the reward for the proposed DNA.
  break

See also:

• pygx.geno.Sweeping
• pygx.geno.Random

Source code in pygx/symbolic/_object.py

@_filter_typing_traceback_on_raise
def __init__(
    self,
    *,
    allow_partial: bool = False,
    sealed: bool | None = None,
    root_path: topology.KeyPath | None = None,
    explicit_init: bool = False,
    **kwargs: Any,
):
    """Create an Object instance.

    ``pg.Object`` synthesizes a keyword-only ``__init__``. Subclasses
    that need positional arguments must override ``__init__``
    explicitly and translate to keyword arguments before forwarding
    to ``super().__init__(**kwargs)``.

    Args:
      allow_partial: If True, the object can be partial.
      sealed: If True, seal the object from future modification (unless under
        a `pg.as_sealed(False)` context manager). If False, treat the object as
        unsealed. If None, it's determined by the class's ``frozen`` option.
      root_path: The symbolic path for current object. By default it's None,
        which indicates that newly constructed object does not have a parent.
      explicit_init: Should set to `True` when `__init__` is called via
        `pg.Object.__init__` instead of `super().__init__`.
      **kwargs: key/value arguments that align with the schema. All required
        keys in the schema must be specified, and values should be acceptable
        according to their value spec.

    Raises:
      TypeError: When a required field is missing, a value has an
        unacceptable type, or an unknown keyword argument is given.
      ValueError: When a value violates its value spec's constraints
        (e.g. out of range).
    """
    # Placeholder for Google-internal usage instrumentation.

    cls = self.__class__
    # The ever-instantiated latch `apply_schema`'s post-instance guard
    # reads (#432: `update_schema` is only legal before instances exist).
    # Own-`__dict__`, latched on the construction ATTEMPT — mirroring the
    # native core, whose `__native_ctor_meta__` (the equivalent marker) is
    # created on the first instance op. One dict read per construct.
    meta = cls.__sym_meta__
    if not meta.instantiated:
        meta.instantiated = True
    if sealed is None:
        sealed = cls.__sym_options__.frozen

    if not isinstance(allow_partial, bool):
        raise TypeError(
            f"Expect bool type for argument 'allow_partial' in "
            f'symbolic.Object.__init__ but encountered {allow_partial}.'
        )

    # Fast path: const-keyed schema.
    if cls._sym_init_fields is not None and self._init_fast_path(
        kwargs,
        allow_partial,
        sealed,
        root_path,
        explicit_init,
    ):
        return

    # Slow path: handles varargs and schemas with non-const keys.

    # Model before-hook (#516) — the fast path was not taken
    # (`_sym_init_fields is None`), so the hook has not run yet.
    if cls._sym_preinit_overridden:
        kwargs = _apply_preinit(cls, kwargs)

    # We delay the seal attempt until members are all set.
    super().__init__(
        allow_partial=allow_partial,
        accessor_writable=cls.__sym_options__.attr_write,
        sealed=sealed,
        root_path=root_path,
        init_super=not explicit_init,
    )

    # Fill field_args and init_args from **kwargs.
    _, unmatched_keys = cls.__schema__.resolve(list(kwargs.keys()))
    # Fields opted out of `__init__` via `enable_init=False` resolve
    # against the schema but must still be rejected as kwargs.
    get_field = cls.__schema__.get_field
    unmatched_keys = list(unmatched_keys) + [
        k
        for k in kwargs
        if (f := get_field(k)) is not None and not f.enable_init
    ]
    if unmatched_keys:
        _screen_unexpected_init_keys(cls, kwargs, unmatched_keys)

    # Declared aliases are RESERVED wire spellings (#517, owner ruling):
    # an open (extra) schema must not accept an extra kwarg equal to a
    # field's alias — the wire would become ambiguous. (Const-keyed
    # schemas never reach here with an alias-spelled kwarg; their
    # unknown-key screen already raised — or, under `extra='ignore'`,
    # raised for alias keys before dropping the rest.)
    if cls._sym_alias_maps is not None:
        alias_to_name = cls._sym_alias_maps[0]
        for k in kwargs:
            if k in alias_to_name:
                raise TypeError(
                    f'{cls.__name__}.__init__() got keyword argument '
                    f'{k!r}, which is reserved as the alias of field '
                    f'{alias_to_name[k]!r}.'
                )

    # All field values come from kwargs — `pg.Object.__init__` is
    # keyword-only.
    field_args = dict(kwargs)

    # Check missing arguments when partial binding is disallowed.
    if not base.accepts_partial(self):
        missing_args = []
        for field in self.__class__.__schema__.fields.values():
            if (
                not field.value.has_default
                and isinstance(field.key, pg_typing.ConstStrKey)
                and field.key not in field_args
            ):
                missing_args.append(str(field.key))
        if missing_args:
            arg_phrase = formatting.auto_plural(
                len(missing_args), 'argument'
            )
            keys_str = formatting.comma_delimited_str(missing_args)
            raise TypeError(
                f'{self.__class__.__name__}.__init__() missing {len(missing_args)} '
                f'required {arg_phrase}: {keys_str}.'
            )

    # NOTE(daiyip): Accessor writable is honored by `Object.__setattr__` so
    # we can always make `_sym_attributes` accessor writable. This prevents
    # a child object's attribute access from being changed when it's
    # attached to a parent whose symbolic attributes are not writable.
    # Per-field validation is gated by `field.enable_validation` inside
    # `Schema.apply` / `Dict._formalized_value` — so a class-wide
    # `validate=False` (resolved into each field) and per-field overrides
    # both flow through naturally here.
    vars(self)['_sym_attributes'] = pg_dict.Dict(
        field_args,  # pyright: ignore[reportArgumentType]
        value_spec=self.__class__.sym_fields,
        allow_partial=allow_partial,
        sealed=sealed,
        accessor_writable=True,
        root_path=root_path,
        as_object_attributes_container=True,
        under_topo=cls.__sym_options__.topo,
    )
    # The write-time `needs_topo` refusal (see `_init_fast_path` Phase 5):
    # the slow path formalizes inside the container, so scan its items.
    if not cls.__sym_options__.topo:
        for k, v in self._sym_attributes.sym_items():
            base.refuse_tree_walking_inferential(cls, k, v)
    self._sym_attributes.topo_setparent(self)
    # Seed `init=False` fields from their defaults before `on_sym_post_init`
    # runs so `on_sym_ready`/`on_sym_bound` overrides start from a known baseline.
    _seed_non_symbolic_fields(self, cls._non_symbolic_fields)
    # Model after-validator (#516): fires before any lifecycle hook can
    # observe the object, gated like `on_sym_ready` (concrete only).
    if cls._sym_validate_overridden:
        abstract = (
            self._allow_partial and self.sym_partial
        ) or self.sym_puresymbolic
        if not abstract:
            self.on_sym_validate()
    self.on_sym_post_init()
    self.sym_seal(sealed)

multi_objective property

multi_objective: bool

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

needs_feedback property

needs_feedback: bool

Returns True if the DNAGenerator needs feedback.

This is detected by whether the subclass overrides _feedback.

num_proposals property

num_proposals

Get number of proposals that are already produced.

num_feedbacks property

num_feedbacks

Get number of proposals whose feedback are provided.

setup

setup(dna_spec: DNASpec) -> None

Set up the generator with a search space definition.

Must be called before propose, feedback or iteration. It resets the proposal/feedback counters and invokes _setup for subclass initialization.

Parameters:

Name	Type	Description	Default
dna_spec	DNASpec	The DNASpec that defines the search space.	required

Source code in pygx/geno/_dna_generator.py

def setup(self, dna_spec: DNASpec) -> None:
    """Set up the generator with a search space definition.

    Must be called before `propose`, `feedback` or iteration. It resets
    the proposal/feedback counters and invokes `_setup` for subclass
    initialization.

    Args:
      dna_spec: The DNASpec that defines the search space.
    """
    self._dna_spec = dna_spec
    self._num_proposals = 0
    self._num_feedbacks = 0
    self._setup()

propose

propose() -> DNA

Proposes a DNA to evaluate.

Returns:

Type	Description
DNA	The proposed DNA.

Raises:

Type	Description
StopIteration	The generator cannot produce more DNAs.

Source code in pygx/geno/_dna_generator.py

def propose(self) -> DNA:
    """Proposes a DNA to evaluate.

    Returns:
      The proposed DNA.

    Raises:
      StopIteration: The generator cannot produce more DNAs.
    """
    dna = self._propose()
    self._num_proposals += 1
    return dna

feedback

feedback(dna: DNA, reward: float | tuple[float]) -> None

Feedback a completed trial to the algorithm.

When the generator does not need feedback (needs_feedback is False), only the feedback counter is updated and _feedback is not called.

Parameters:

Name	Type	Description	Default
dna	DNA	a DNA object.	required
reward	float | tuple[float]	reward for the DNA. It is a float if self.multi_objective returns False, otherwise it's a tuple of floats.	required

Source code in pygx/geno/_dna_generator.py

def feedback(self, dna: DNA, reward: float | tuple[float]) -> None:
    """Feedback a completed trial to the algorithm.

    When the generator does not need feedback (`needs_feedback` is
    False), only the feedback counter is updated and `_feedback` is not
    called.

    Args:
      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.
    """
    if self.needs_feedback:
        if self.multi_objective and isinstance(reward, float):
            reward = (reward,)
        elif not self.multi_objective and isinstance(reward, tuple):
            if len(reward) != 1:
                raise ValueError(
                    f'{self!r} is single objective, but the reward {reward!r} '
                    f'contains multiple objectives.'
                )
            reward = reward[0]
        self._feedback(dna, reward)
    self._num_feedbacks += 1

recover

recover(history: Iterable[tuple[DNA, None | float | tuple[float]]]) -> None

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.

Parameters:

Name	Type	Description	Default
history	Iterable[tuple[DNA, None | float | tuple[float]]]	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).	required

Source code in pygx/geno/_dna_generator.py

def recover(
    self, history: Iterable[tuple[DNA, None | float | tuple[float]]]
) -> None:
    """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.

    Args:
      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).
    """
    for i, (dna, reward) in enumerate(history):
        self._replay(i, dna, reward)
        self._num_proposals += 1
        if reward is not None:
            self._num_feedbacks += 1

Float

Float(min_value: float, max_value: float, **kwargs)

Bases: DecisionPoint

Represents the genotype for a float-value genome.

Example:

# Create a float decision point within range [0.1, 1.0].
decision_point = pg.geno.floatv(0.1, 1.0)

See also: pygx.geno.floatv.

Source code in pygx/geno/_numerical.py

def __init__(self, min_value: float, max_value: float, **kwargs):
    super().__init__(
        **dict(min_value=min_value, max_value=max_value),
        **kwargs,
    )

is_categorical property

is_categorical: bool

Returns True if current node is a categorical choice.

is_subchoice property

is_subchoice: bool

Returns True if current node is a subchoice of a multi-choice.

is_numerical property

is_numerical: bool

Returns True if current node is numerical decision.

is_custom_decision_point property

is_custom_decision_point: bool

Returns True if current node is a custom decision point.

decision_points property

decision_points: list[DecisionPoint]

Returns all decision points in their declaration order.

space_size property

space_size: int

Returns the size of the search space, or -1 if infinite.

on_sym_bound

on_sym_bound()

Custom logics to validate value.

Source code in pygx/geno/_numerical.py

def on_sym_bound(self):
    """Custom logics to validate value."""
    super().on_sym_bound()
    if self.min_value > self.max_value:
        raise ValueError(
            f"Argument 'min_value' ({self.min_value}) should be no greater "
            f"than 'max_value' ({self.max_value})."
        )
    if self.scale in ['log', 'rlog'] and self.min_value <= 0:
        raise ValueError(
            f"'min_value' must be positive when `scale` is {self.scale!r}. "
            f'encountered: {self.min_value}.'
        )

validate

validate(dna: DNA) -> None

Validate whether a DNA value conforms to this spec.

Source code in pygx/geno/_numerical.py

def validate(self, dna: DNA) -> None:
    """Validate whether a DNA value conforms to this spec."""
    if not isinstance(dna.value, float):
        raise ValueError(
            f'Expect float value. Encountered: {dna.value}, '
            f'Location: {self.location.path}.'
        )
    if dna.value < self.min_value:
        raise ValueError(
            f'DNA value should be no less than {self.min_value}. '
            f'Encountered {dna.value}, Location: {self.location.path}.'
        )
    if dna.value > self.max_value:
        raise ValueError(
            f'DNA value should be no greater than {self.max_value}. '
            f'Encountered {dna.value}, Location: {self.location.path}.'
        )
    if dna.children:
        raise ValueError(
            f'Float DNA should have no children. '
            f'Encountered: {dna.children!r}, Location: {self.location.path}.'
        )

format

format(
    compact: bool = True,
    verbose: bool = True,
    root_indent: int = 0,
    show_id: bool = True,
    **kwargs
)

Format this object.

Source code in pygx/geno/_numerical.py

def format(
    self,
    compact: bool = True,
    verbose: bool = True,
    root_indent: int = 0,
    show_id: bool = True,
    **kwargs,
):
    """Format this object."""
    if not compact:
        return super().format(compact, verbose, root_indent, **kwargs)
    kvlist: list[tuple[str, Any, Any]]
    if show_id:
        kvlist = [('id', str(self.id), "''")]
    else:
        kvlist = []
    details = formatting.kvlist_str(
        kvlist
        + [
            ('name', self.name, None),
            ('min_value', self.min_value, None),
            ('max_value', self.max_value, None),
            ('scale', self.scale, None),
            ('hints', self.hints, None),
        ]
    )
    return f'{self.__class__.__name__}({details})'

Random

Random(seed: int | None = None, **kwargs)

Bases: DNAGenerator

Random DNA generator.

Proposes uniformly random DNAs from the search space, independent of any feedback. When seed is None, the global random module is used; otherwise a dedicated random.Random(seed) is used, which makes the proposal sequence reproducible - state recovery replays the sequence by re-generating past proposals.

Example:

search_space = pg.geno.space([
    pg.geno.oneof([pg.geno.constant(), pg.geno.constant()])
])
generator = pg.geno.Random(seed=1)
generator.setup(search_space)
dna = generator.propose()

Source code in pygx/geno/_random.py

def __init__(self, seed: int | None = None, **kwargs):
    super().__init__(**dict(seed=seed), **kwargs)

Space

Space(elements: list[DecisionPoint] | None = None, **kwargs)

Bases: DNASpec

Represents a search space that consists of a list of decision points.

Example:

# Create a constant space.
space = pg.geno.Space([])

# Create a space with one categorical decision point
# and a float decision point
space = pg.geno.space([
    pg.geno.oneof([
        pg.geno.constant(),
        pg.geno.constant(),
    ]),
    pg.geno.floatv(0.0, 1.0)
])

See also: pygx.geno.constant.

Source code in pygx/geno/_space.py

def __init__(
    self,
    elements: list[DecisionPoint] | None = None,
    **kwargs,
):
    # `elements=None` means "use schema default" (an empty list). The
    # schema's deep-copy of the default avoids the mutable-default
    # sharing problem.
    if elements is not None:
        kwargs['elements'] = elements
    super().__init__(**kwargs)

is_space property

is_space: bool

Returns True if current node is a sub-space.

is_categorical property

is_categorical: bool

Returns True if current node is a categorical choice.

is_subchoice property

is_subchoice: bool

Returns True if current node is a subchoice of a multi-choice.

is_numerical property

is_numerical: bool

Returns True if current node is numerical decision.

is_custom_decision_point property

is_custom_decision_point: bool

Returns True if current node is a custom decision point.

is_constant property

is_constant: bool

Returns whether this space is constant.

A constant Space does not have any decision points.

decision_points property

decision_points: list[DecisionPoint]

Returns all decision points in their declaration order.

space_size property

space_size: int

Returns the size of the search space, or -1 if infinite.

validate

validate(dna: DNA) -> None

Validate whether a DNA value conforms to this spec.

Source code in pygx/geno/_space.py

def validate(self, dna: DNA) -> None:  # pytype: disable=signature-mismatch
    """Validate whether a DNA value conforms to this spec."""
    if not self.elements and (dna.value is not None or dna.children):
        raise ValueError(
            f'Extra DNA values encountered: {dna!r}, '
            f'Location: {self.location.path}.'
        )

    if len(self.elements) == 1:
        self.elements[0].validate(dna)
    else:
        if len(dna.children) != len(self.elements):
            raise ValueError(
                f'Number of child values in DNA ({len(dna.children)}) does not '
                f'match the number of elements ({len(self.elements)}). Child '
                f'values: {dna.children!r}, Location: {self.location.path}.'
            )
        for i, elem in enumerate(self.elements):
            # `DNA.__getitem__` is union-typed (`DNA | list[...] | None`),
            # but for a multi-element Space the i-th child is always a
            # `DNA` once the length-check above passes.
            elem.validate(dna[i])  # pyright: ignore[reportArgumentType]

format

format(
    compact: bool = True, verbose: bool = True, root_indent: int = 0, **kwargs
)

Format this object.

Source code in pygx/geno/_space.py

def format(
    self,
    compact: bool = True,
    verbose: bool = True,
    root_indent: int = 0,
    **kwargs,
):
    """Format this object."""
    if not compact:
        return super().format(compact, verbose, root_indent, **kwargs)

    if not self.elements:
        return 'Space()'

    def _indent(text, indent):
        return ' ' * 2 * indent + text

    s = ['Space({\n']
    for i, elem in enumerate(self.elements):
        elem_str = elem.format(
            compact, verbose, root_indent + 1, show_id=False, **kwargs
        )
        s.append(
            _indent(
                f"{i} = '{elem.location.path}': {elem_str}\n",
                root_indent + 1,
            )
        )
    s.append(_indent('}', root_indent))
    s.append(')')
    return ''.join(s)

Sweeping

Sweeping(
    *,
    allow_partial: bool = False,
    sealed: bool | None = None,
    root_path: KeyPath | None = None,
    explicit_init: bool = False,
    **kwargs: Any
)

Bases: DNAGenerator

Sweeping (Grid Search) DNA generator.

Enumerates every DNA in the search space exactly once, in the enumeration order defined by DNASpec.next_dna (last decision point advances first). It takes no feedback, and raises StopIteration when the space is exhausted, which ends iteration.

Example:

search_space = pg.geno.space([
    pg.geno.oneof([pg.geno.constant(), pg.geno.constant()])
])
generator = pg.geno.Sweeping()
generator.setup(search_space)
print([str(dna) for dna in generator])
# ['DNA(0)', 'DNA(1)']

Note: spaces containing Float or custom decision points without a next_dna_fn cannot be swept.

Source code in pygx/symbolic/_object.py

@_filter_typing_traceback_on_raise
def __init__(
    self,
    *,
    allow_partial: bool = False,
    sealed: bool | None = None,
    root_path: topology.KeyPath | None = None,
    explicit_init: bool = False,
    **kwargs: Any,
):
    """Create an Object instance.

    ``pg.Object`` synthesizes a keyword-only ``__init__``. Subclasses
    that need positional arguments must override ``__init__``
    explicitly and translate to keyword arguments before forwarding
    to ``super().__init__(**kwargs)``.

    Args:
      allow_partial: If True, the object can be partial.
      sealed: If True, seal the object from future modification (unless under
        a `pg.as_sealed(False)` context manager). If False, treat the object as
        unsealed. If None, it's determined by the class's ``frozen`` option.
      root_path: The symbolic path for current object. By default it's None,
        which indicates that newly constructed object does not have a parent.
      explicit_init: Should set to `True` when `__init__` is called via
        `pg.Object.__init__` instead of `super().__init__`.
      **kwargs: key/value arguments that align with the schema. All required
        keys in the schema must be specified, and values should be acceptable
        according to their value spec.

    Raises:
      TypeError: When a required field is missing, a value has an
        unacceptable type, or an unknown keyword argument is given.
      ValueError: When a value violates its value spec's constraints
        (e.g. out of range).
    """
    # Placeholder for Google-internal usage instrumentation.

    cls = self.__class__
    # The ever-instantiated latch `apply_schema`'s post-instance guard
    # reads (#432: `update_schema` is only legal before instances exist).
    # Own-`__dict__`, latched on the construction ATTEMPT — mirroring the
    # native core, whose `__native_ctor_meta__` (the equivalent marker) is
    # created on the first instance op. One dict read per construct.
    meta = cls.__sym_meta__
    if not meta.instantiated:
        meta.instantiated = True
    if sealed is None:
        sealed = cls.__sym_options__.frozen

    if not isinstance(allow_partial, bool):
        raise TypeError(
            f"Expect bool type for argument 'allow_partial' in "
            f'symbolic.Object.__init__ but encountered {allow_partial}.'
        )

    # Fast path: const-keyed schema.
    if cls._sym_init_fields is not None and self._init_fast_path(
        kwargs,
        allow_partial,
        sealed,
        root_path,
        explicit_init,
    ):
        return

    # Slow path: handles varargs and schemas with non-const keys.

    # Model before-hook (#516) — the fast path was not taken
    # (`_sym_init_fields is None`), so the hook has not run yet.
    if cls._sym_preinit_overridden:
        kwargs = _apply_preinit(cls, kwargs)

    # We delay the seal attempt until members are all set.
    super().__init__(
        allow_partial=allow_partial,
        accessor_writable=cls.__sym_options__.attr_write,
        sealed=sealed,
        root_path=root_path,
        init_super=not explicit_init,
    )

    # Fill field_args and init_args from **kwargs.
    _, unmatched_keys = cls.__schema__.resolve(list(kwargs.keys()))
    # Fields opted out of `__init__` via `enable_init=False` resolve
    # against the schema but must still be rejected as kwargs.
    get_field = cls.__schema__.get_field
    unmatched_keys = list(unmatched_keys) + [
        k
        for k in kwargs
        if (f := get_field(k)) is not None and not f.enable_init
    ]
    if unmatched_keys:
        _screen_unexpected_init_keys(cls, kwargs, unmatched_keys)

    # Declared aliases are RESERVED wire spellings (#517, owner ruling):
    # an open (extra) schema must not accept an extra kwarg equal to a
    # field's alias — the wire would become ambiguous. (Const-keyed
    # schemas never reach here with an alias-spelled kwarg; their
    # unknown-key screen already raised — or, under `extra='ignore'`,
    # raised for alias keys before dropping the rest.)
    if cls._sym_alias_maps is not None:
        alias_to_name = cls._sym_alias_maps[0]
        for k in kwargs:
            if k in alias_to_name:
                raise TypeError(
                    f'{cls.__name__}.__init__() got keyword argument '
                    f'{k!r}, which is reserved as the alias of field '
                    f'{alias_to_name[k]!r}.'
                )

    # All field values come from kwargs — `pg.Object.__init__` is
    # keyword-only.
    field_args = dict(kwargs)

    # Check missing arguments when partial binding is disallowed.
    if not base.accepts_partial(self):
        missing_args = []
        for field in self.__class__.__schema__.fields.values():
            if (
                not field.value.has_default
                and isinstance(field.key, pg_typing.ConstStrKey)
                and field.key not in field_args
            ):
                missing_args.append(str(field.key))
        if missing_args:
            arg_phrase = formatting.auto_plural(
                len(missing_args), 'argument'
            )
            keys_str = formatting.comma_delimited_str(missing_args)
            raise TypeError(
                f'{self.__class__.__name__}.__init__() missing {len(missing_args)} '
                f'required {arg_phrase}: {keys_str}.'
            )

    # NOTE(daiyip): Accessor writable is honored by `Object.__setattr__` so
    # we can always make `_sym_attributes` accessor writable. This prevents
    # a child object's attribute access from being changed when it's
    # attached to a parent whose symbolic attributes are not writable.
    # Per-field validation is gated by `field.enable_validation` inside
    # `Schema.apply` / `Dict._formalized_value` — so a class-wide
    # `validate=False` (resolved into each field) and per-field overrides
    # both flow through naturally here.
    vars(self)['_sym_attributes'] = pg_dict.Dict(
        field_args,  # pyright: ignore[reportArgumentType]
        value_spec=self.__class__.sym_fields,
        allow_partial=allow_partial,
        sealed=sealed,
        accessor_writable=True,
        root_path=root_path,
        as_object_attributes_container=True,
        under_topo=cls.__sym_options__.topo,
    )
    # The write-time `needs_topo` refusal (see `_init_fast_path` Phase 5):
    # the slow path formalizes inside the container, so scan its items.
    if not cls.__sym_options__.topo:
        for k, v in self._sym_attributes.sym_items():
            base.refuse_tree_walking_inferential(cls, k, v)
    self._sym_attributes.topo_setparent(self)
    # Seed `init=False` fields from their defaults before `on_sym_post_init`
    # runs so `on_sym_ready`/`on_sym_bound` overrides start from a known baseline.
    _seed_non_symbolic_fields(self, cls._non_symbolic_fields)
    # Model after-validator (#516): fires before any lifecycle hook can
    # observe the object, gated like `on_sym_ready` (concrete only).
    if cls._sym_validate_overridden:
        abstract = (
            self._allow_partial and self.sym_partial
        ) or self.sym_puresymbolic
        if not abstract:
            self.on_sym_validate()
    self.on_sym_post_init()
    self.sym_seal(sealed)

manyof

manyof(
    num_choices: int,
    candidates: list[DNASpec],
    distinct: bool = True,
    sorted: bool = False,
    literal_values: list[str | int | float] | None = None,
    hints: Any = None,
    location: str | KeyPath = KeyPath(),
    name: str | None = None,
) -> Choices

Returns a multi-choice specification.

It creates the genotype for pygx.manyof.

Example:

spec = pg.geno.manyof(2, [
    pg.geno.constant(),
    pg.geno.constant(),
    pg.geno.oneof([
        pg.geno.constant(),
        pg.geno.constant()
    ])
])

Parameters:

Name	Type	Description	Default
num_choices	int	Number of choices.	required
candidates	list[DNASpec]	A list of pg.geno.Space or pg.geno.DecisionPoint objects as the candidates. A decision point is automatically wrapped into a single-element space.	required
distinct	bool	If True, the decisions for the multiple choices should be distinct from each other (based on the value of selected indices).	True
sorted	bool	If True, the decisions returned should be sorted by the values of selected indices.	False
literal_values	list[str | int | float] | None	An optional list of string, integer, or float as the literal values for the candidates for display purpose.	None
hints	Any	An optional hint object.	None
location	str | KeyPath	A pg.KeyPath object that indicates the location of the decision point.	KeyPath()
name	str | None	An optional global unique name for identifying this decision point.	None

Returns:

Type	Description
Choices	A pg.geno.Choices object.

See also:

• pygx.geno.constant
• pygx.geno.oneof
• pygx.geno.floatv

Source code in pygx/geno/_categorical.py

def manyof(
    num_choices: int,
    candidates: list[DNASpec],
    distinct: bool = True,
    sorted: bool = False,  # pylint: disable=redefined-builtin
    literal_values: list[str | int | float] | None = None,
    hints: Any = None,
    location: str | topology.KeyPath = topology.KeyPath(),
    name: str | None = None,
) -> Choices:
    """Returns a multi-choice specification.

    It creates the genotype for [`pygx.manyof`][pygx.hyper.manyof].

    **Example:**

    ```python
    spec = pg.geno.manyof(2, [
        pg.geno.constant(),
        pg.geno.constant(),
        pg.geno.oneof([
            pg.geno.constant(),
            pg.geno.constant()
        ])
    ])
    ```

    Args:
      num_choices: Number of choices.
      candidates: A list of ``pg.geno.Space`` or ``pg.geno.DecisionPoint``
        objects as the candidates. A decision point is automatically
        wrapped into a single-element space.
      distinct: If True, the decisions for the multiple choices should be
        distinct from each other (based on the value of selected indices).
      sorted: If True, the decisions returned should be sorted by the
        values of selected indices.
      literal_values: An optional list of string, integer, or float as the
        literal values for the candidates for display purpose.
      hints: An optional hint object.
      location: A ``pg.KeyPath`` object that indicates the location of the
        decision point.
      name: An optional global unique name for identifying this decision
        point.

    Returns:
      A ``pg.geno.Choices`` object.

    See also:

      * [`pygx.geno.constant`][pygx.geno.constant]
      * [`pygx.geno.oneof`][pygx.geno.oneof]
      * [`pygx.geno.floatv`][pygx.geno.floatv]
    """
    normalized_candidates = []
    for c in candidates:
        if isinstance(c, DecisionPoint):
            c = Space(elements=[c])
        normalized_candidates.append(c)
    return Choices(
        num_choices=num_choices,
        candidates=normalized_candidates,
        distinct=distinct,
        sorted=sorted,
        literal_values=literal_values,
        hints=hints,
        location=location,
        name=name,
    )

oneof

oneof(
    candidates: list[DNASpec],
    literal_values: list[str | int | float] | None = None,
    hints: Any = None,
    location: str | KeyPath = KeyPath(),
    name: str | None = None,
) -> Choices

Returns a single choice specification.

It creates the genotype for pygx.oneof.

Example:

spec = pg.geno.oneof([
    pg.geno.constant(),
    pg.geno.oneof([
        pg.geno.constant(),
        pg.geno.constant()
    ])
])

Parameters:

Name	Type	Description	Default
candidates	list[DNASpec]	A list of pg.geno.Space or pg.geno.DecisionPoint objects as the candidates. A decision point is automatically wrapped into a single-element space.	required
literal_values	list[str | int | float] | None	An optional list of string, integer, or float as the literal values for the candidates for display purpose.	None
hints	Any	An optional hint object.	None
location	str | KeyPath	A pg.KeyPath object that indicates the location of the decision point.	KeyPath()
name	str | None	An optional global unique name for identifying this decision point.	None

Returns:

Type	Description
Choices	A pg.geno.Choices object.

See also:

• pygx.geno.constant
• pygx.geno.manyof
• pygx.geno.floatv

Source code in pygx/geno/_categorical.py

def oneof(
    candidates: list[DNASpec],
    literal_values: list[str | int | float] | None = None,
    hints: Any = None,
    location: str | topology.KeyPath = topology.KeyPath(),
    name: str | None = None,
) -> Choices:
    """Returns a single choice specification.

    It creates the genotype for [`pygx.oneof`][pygx.hyper.oneof].

    **Example:**

    ```python
    spec = pg.geno.oneof([
        pg.geno.constant(),
        pg.geno.oneof([
            pg.geno.constant(),
            pg.geno.constant()
        ])
    ])
    ```

    Args:
      candidates: A list of ``pg.geno.Space`` or ``pg.geno.DecisionPoint``
        objects as the candidates. A decision point is automatically
        wrapped into a single-element space.
      literal_values: An optional list of string, integer, or float as the
        literal values for the candidates for display purpose.
      hints: An optional hint object.
      location: A ``pg.KeyPath`` object that indicates the location of the
        decision point.
      name: An optional global unique name for identifying this decision
        point.

    Returns:
      A ``pg.geno.Choices`` object.

    See also:

      * [`pygx.geno.constant`][pygx.geno.constant]
      * [`pygx.geno.manyof`][pygx.geno.manyof]
      * [`pygx.geno.floatv`][pygx.geno.floatv]
    """
    return manyof(
        1,
        candidates,
        literal_values=literal_values,
        hints=hints,
        location=location,
        name=name,
    )

custom

custom(
    hyper_type: str | None = None,
    next_dna_fn: Callable[[DNA | None], DNA | None] | None = None,
    random_dna_fn: Callable[[Any, DNA | None], DNA] | None = None,
    hints: Any = None,
    location: KeyPath = KeyPath(),
    name: str | None = None,
) -> CustomDecisionPoint

Returns a custom decision point.

It creates the genotype for subclasses of pygx.hyper.CustomHyper.

Example:

spec = pg.geno.custom('my_hyper', hints='some hints')

Parameters:

Name	Type	Description	Default
hyper_type	str | None	An optional display type for the custom decision point.	None
next_dna_fn	Callable[[DNA | None], DNA | None] | None	An optional callable for computing the next DNA for current decision point.	None
random_dna_fn	Callable[[Any, DNA | None], DNA] | None	An optional callable for computing a random DNA for current decision point.	None
hints	Any	An optional hint object.	None
location	KeyPath	A pg.KeyPath object that indicates the location of the decision point.	KeyPath()
name	str | None	An optional global unique name for identifying this decision point.	None

Returns:

Type	Description
CustomDecisionPoint	A pg.geno.CustomDecisionPoint object.

See also:

• pygx.geno.constant
• pygx.geno.oneof
• pygx.geno.manyof
• pygx.geno.floatv

Source code in pygx/geno/_custom.py

def custom(
    hyper_type: str | None = None,
    next_dna_fn: Callable[[DNA | None], DNA | None] | None = None,
    random_dna_fn: Callable[[Any, DNA | None], DNA] | None = None,
    hints: Any = None,
    location: topology.KeyPath = topology.KeyPath(),
    name: str | None = None,
) -> CustomDecisionPoint:
    """Returns a custom decision point.

    It creates the genotype for subclasses of [`pygx.hyper.CustomHyper`][pygx.hyper.CustomHyper].

    **Example:**

    ```python
    spec = pg.geno.custom('my_hyper', hints='some hints')
    ```

    Args:
      hyper_type: An optional display type for the custom decision point.
      next_dna_fn: An optional callable for computing the next DNA for current
        decision point.
      random_dna_fn: An optional callable for computing a random DNA for current
        decision point.
      hints: An optional hint object.
      location: A ``pg.KeyPath`` object that indicates the location of the
        decision point.
      name: An optional global unique name for identifying this decision
        point.

    Returns:
      A ``pg.geno.CustomDecisionPoint`` object.

    See also:

      * [`pygx.geno.constant`][pygx.geno.constant]
      * [`pygx.geno.oneof`][pygx.geno.oneof]
      * [`pygx.geno.manyof`][pygx.geno.manyof]
      * [`pygx.geno.floatv`][pygx.geno.floatv]
    """
    return CustomDecisionPoint(
        hyper_type=hyper_type,
        next_dna_fn=next_dna_fn,
        random_dna_fn=random_dna_fn,
        hints=hints,
        location=location,
        name=name,
    )

dna_generator

dna_generator(func: Callable[[DNASpec], Iterator[DNA]]) -> type[DNAGenerator]

Decorator that converts a generation function to a DNAGenerator class.

The decorated function takes the search space definition (a DNASpec) and yields DNAs; each propose call pulls the next item from the iterator, and exhausting the iterator ends the generator (StopIteration).

Example:

@pg.geno.dna_generator
def first_ten(dna_spec):
  dna = None
  for _ in range(10):
    dna = dna_spec.next_dna(dna)
    if dna is None:
      break
    yield dna

# The decorator returns a DNAGenerator subclass, which is instantiated
# with no arguments.
generator = first_ten()
generator.setup(pg.geno.space([
    pg.geno.oneof([pg.geno.constant(), pg.geno.constant()])
]))
print([str(dna) for dna in generator])
# ['DNA(0)', 'DNA(1)']

Another example that reads DNAs from a file:

def from_file(filepath):
  @pg.geno.dna_generator
  def file_based_dna_generator(dna_spec):
    dna_list = pg.load(filepath)
    for dna in dna_list:
      dna.use_spec(dna_spec)
      yield dna

  return file_based_dna_generator

See also: pygx.DNAGenerator

Parameters:

Name	Type	Description	Default
func	Callable[[DNASpec], Iterator[DNA]]	the generation function in signature: (DNASpec) -> Iterator[DNA]	required

Returns:

Type	Description
type[DNAGenerator]	A DNAGenerator class.

Source code in pygx/geno/_dna_generator.py

def dna_generator(
    func: Callable[[DNASpec], Iterator[DNA]],
) -> type['DNAGenerator']:
    """Decorator that converts a generation function to a DNAGenerator class.

    The decorated function takes the search space definition (a DNASpec) and
    yields DNAs; each `propose` call pulls the next item from the iterator,
    and exhausting the iterator ends the generator (`StopIteration`).

    **Example:**

    ```python
    @pg.geno.dna_generator
    def first_ten(dna_spec):
      dna = None
      for _ in range(10):
        dna = dna_spec.next_dna(dna)
        if dna is None:
          break
        yield dna

    # The decorator returns a DNAGenerator subclass, which is instantiated
    # with no arguments.
    generator = first_ten()
    generator.setup(pg.geno.space([
        pg.geno.oneof([pg.geno.constant(), pg.geno.constant()])
    ]))
    print([str(dna) for dna in generator])
    # ['DNA(0)', 'DNA(1)']
    ```

    Another example that reads DNAs from a file:

    ```python
    def from_file(filepath):
      @pg.geno.dna_generator
      def file_based_dna_generator(dna_spec):
        dna_list = pg.load(filepath)
        for dna in dna_list:
          dna.use_spec(dna_spec)
          yield dna

      return file_based_dna_generator
    ```

    See also: [`pygx.DNAGenerator`][pygx.geno.DNAGenerator]

    Args:
      func: the generation function in signature:
        `(DNASpec) -> Iterator[DNA]`

    Returns:
      A DNAGenerator class.
    """

    class SimpleDNAGenerator(DNAGenerator):
        """Simple DNA generator."""

        def _setup(self):
            self._iterator = func(self.dna_spec)  # pyright: ignore[reportArgumentType]
            self._error = None

        def _propose(self) -> DNA:
            if self._error is not None:
                raise ValueError(
                    f'Error happened earlier: {self._error}'
                ) from self._error
            try:
                return next(self._iterator)
            except Exception as e:
                if not isinstance(e, StopIteration):
                    self._error = e
                raise

    return SimpleDNAGenerator

floatv

floatv(
    min_value: float,
    max_value: float,
    scale: str | None = None,
    hints: Any = None,
    location: KeyPath = KeyPath(),
    name: str | None = None,
) -> Float

Returns a Float specification.

It creates the genotype for pygx.floatv.

Example:

spec = pg.geno.floatv(0.0, 1.0)

Parameters:

Name	Type	Description	Default
min_value	float	The lower bound of decision.	required
max_value	float	The upper bound of decision.	required
scale	str | None	An optional string as the scale of the range. Supported values are None, 'linear', 'log', and 'rlog'. If None, the feasible space is unscaled. If linear, the feasible space is mapped to [0, 1] linearly. If log, the feasible space is mapped to [0, 1] logarithmically with formula x -> log(x / min) / log(max / min). If rlog, the feasible space is mapped to [0, 1] "reverse" logarithmically, resulting in values close to max_value spread out more than the points near the min_value, with formula: x -> 1.0 - log((max + min - x) / min) / log (max / min). min_value must be positive if scale is not None. Also, it depends on the search algorithm to decide whether this information is used or not.	None
hints	Any	An optional hint object.	None
location	KeyPath	A pg.KeyPath object that indicates the location of the decision point.	KeyPath()
name	str | None	An optional global unique name for identifying this decision point.	None

Returns:

Type	Description
Float	A pg.geno.Float object.

See also:

• pygx.geno.constant
• pygx.geno.oneof
• pygx.geno.manyof

Source code in pygx/geno/_numerical.py

def floatv(
    min_value: float,
    max_value: float,
    scale: str | None = None,
    hints: Any = None,
    location: topology.KeyPath = topology.KeyPath(),
    name: str | None = None,
) -> Float:
    """Returns a Float specification.

    It creates the genotype for [`pygx.floatv`][pygx.hyper.floatv].

    **Example:**

    ```python
    spec = pg.geno.floatv(0.0, 1.0)
    ```

    Args:
      min_value: The lower bound of decision.
      max_value: The upper bound of decision.
      scale: An optional string as the scale of the range. Supported values
        are None, 'linear', 'log', and 'rlog'.
        If None, the feasible space is unscaled.
        If `linear`, the feasible space is mapped to [0, 1] linearly.
        If `log`, the feasible space is mapped to [0, 1] logarithmically with
          formula `x -> log(x / min) / log(max / min)`.
        If `rlog`, the feasible space is mapped to [0, 1] "reverse"
          logarithmically, resulting in values close to `max_value` spread
          out more than the points near the `min_value`, with formula:
          x -> 1.0 - log((max + min - x) / min) / log (max / min).
        `min_value` must be positive if `scale` is not None.
        Also, it depends on the search algorithm to decide whether this
        information is used or not.
      hints: An optional hint object.
      location: A ``pg.KeyPath`` object that indicates the location of the
        decision point.
      name: An optional global unique name for identifying this decision
        point.

    Returns:
      A ``pg.geno.Float`` object.

    See also:

      * [`pygx.geno.constant`][pygx.geno.constant]
      * [`pygx.geno.oneof`][pygx.geno.oneof]
      * [`pygx.geno.manyof`][pygx.geno.manyof]
    """
    return Float(
        min_value=min_value,
        max_value=max_value,
        scale=scale,
        hints=hints,
        location=location,
        name=name,
    )

random_dna

random_dna(
    dna_spec: DNASpec,
    random_generator: None | ModuleType | Random = None,
    attach_spec: bool = True,
    previous_dna: DNA | None = None,
) -> DNA

Generates a random DNA from a DNASpec.

Example:

spec = pg.geno.space([
    pg.geno.oneof([
        pg.geno.constant(),
        pg.geno.constant(),
        pg.geno.constant()
    ]),
    pg.geno.floatv(0.1, 0.2)
])

print(pg.random_dna(spec))
# Example output: DNA([1, 0.18935385454561734])

Parameters:

Name	Type	Description	Default
dna_spec	DNASpec	a DNASpec object.	required
random_generator	None | ModuleType | Random	a Python random generator.	None
attach_spec	bool	If True, attach the DNASpec to generated DNA.	True
previous_dna	DNA | None	An optional DNA representing previous DNA. This field might be useful for generating stateful random DNAs.	None

Returns:

Type	Description
DNA	A DNA object.

Source code in pygx/geno/_random.py

def random_dna(
    dna_spec: DNASpec,
    random_generator: None | types.ModuleType | random.Random = None,
    attach_spec: bool = True,
    previous_dna: DNA | None = None,
) -> DNA:
    """Generates a random DNA from a DNASpec.

    **Example:**

    ```python
    spec = pg.geno.space([
        pg.geno.oneof([
            pg.geno.constant(),
            pg.geno.constant(),
            pg.geno.constant()
        ]),
        pg.geno.floatv(0.1, 0.2)
    ])

    print(pg.random_dna(spec))
    # Example output: DNA([1, 0.18935385454561734])
    ```

    Args:
      dna_spec: a DNASpec object.
      random_generator: a Python random generator.
      attach_spec: If True, attach the DNASpec to generated DNA.
      previous_dna: An optional DNA representing previous DNA. This field might
          be useful for generating stateful random DNAs.

    Returns:
      A DNA object.
    """
    return dna_spec.random_dna(
        random_generator or random, attach_spec, previous_dna
    )

constant

constant() -> Space

Returns a constant candidate (an empty space) for Choices.

Example:

spec = pg.geno.constant()

Returns:

Type	Description
Space	a constant pg.geno.Space object.

See also:

• pygx.geno.oneof
• pygx.geno.manyof
• pygx.geno.floatv

Source code in pygx/geno/_space.py

def constant() -> Space:
    """Returns a constant candidate (an empty space) for Choices.

    **Example:**

    ```python
    spec = pg.geno.constant()
    ```

    Returns:
      a constant ``pg.geno.Space`` object.

    See also:

      * [`pygx.geno.oneof`][pygx.geno.oneof]
      * [`pygx.geno.manyof`][pygx.geno.manyof]
      * [`pygx.geno.floatv`][pygx.geno.floatv]
    """
    return Space()

options: show_root_heading: false show_root_toc_entry: false members_order: source heading_level: 2