Symbolic Object¶

A symbolic object is a Python object that can be symbolically programmed. It has the characteristics of a regular object — data members and methods that can be accessed and executed at runtime — and additionally functions as a symbolic representation, allowing it to be manipulated as a node in the symbolic tree.

In other words, a symbolic object can be both manipulated and executed. The two aspects are always in sync, meaning that when the object is manipulated, its states are adjusted accordingly to maintain consistency.

flowchart LR
    sym["<b>Symbolic representation</b><br/>(sym_init_args, schema,<br/>parent, path)"]
    exec["<b>Executable state</b><br/>(instance attributes,<br/>methods)"]
    sym <-->|sym_rebind / on_sym_change| exec

Symbolic objects opt in with sym=True

A plain class Foo(pg.Object) is a flat, validated object by default — it does not join the symbolic tree. Everything on this page that involves tree structure — sym_path / sym_parent, sym_rebind, adoption, parent/path change events — requires a class declared with class Foo(pg.Object, sym=True) (the mode is inherited by subclasses). Types created with pg.symbolize / pg.functor, as in the examples below, are symbolic already.

Symbolization¶

Symbolic objects are instances of symbolic types in PyGX. PyGX allows the creation of new symbolic types as well as extending existing types with symbolic programmability. This process is called symbolization. pg.symbolize is the API for symbolization:

@pg.symbolize
def foo(x, y):
    return x + y


# `f` is an instance of `foo`, a symbolic object representing a bound function.
f = foo(1, 2)


@pg.symbolize
class Foo:

    def __init__(self, x, y):
        self._x = x
        self._y = y

    def sum(self):
        return self._x + self._y


# `f` is an instance of `Foo`, which is also a symbolic object.
f = Foo(1, 2)

pg.symbolize allows various options, such as enabling symbolic validation and using symbolic equality as the default comparison method. Symbolic classes can also be created by subclassing pg.Object. For more details on developing symbolic types, see Types.

Logical layout¶

A symbolic object carries symbolic attributes, which are the stored argument values from __init__ and serve as the symbolic representation for the object. When any symbolic attribute is modified, PyGX recomputes the object's states based on the latest symbolic attributes. To notify the containing object when it's modified, a symbolic object also maintains a reference to its parent object.

classDiagram
    class SymbolicObject {
        +sym_init_args : Dict
        +sym_parent : Symbolic | None
        +sym_path : KeyPath
        +__schema__ : Schema
        +instance attrs (computed)
        +sym_rebind(...)
        +on_sym_change(updates)
    }
    SymbolicObject --> SymbolicObject : sym_parent

Symbolic tree¶

A symbolic attribute is usually a value of a simple type (e.g., int, str) or a reference to another symbolic object. When multiple symbolic objects are linked together this way, they form a tree-like structure of symbols. Each object in the tree is identified by a unique combination of keys, which we call a key path (pg.KeyPath). Key paths can be used to navigate and manipulate specific nodes in the symbolic tree:

@pg.symbolize
def node(value, children=None):
    pass


tree = node(1, [
    node(2, [node(3), node(4)]),
    node(5, [node(6), node(7)]),
])

# Mutate a tree by key paths.
tree.sym_rebind({
    # Mutate the root node's value from 1 to 8.
    'value': 8,

    # Mutate the first grandchild node's value from 3 to 9.
    'children[0].children[0].value': 9,
})

Values of symbolic attributes¶

Users are not required to use symbolic values for symbolic attributes, but it is recommended. Symbolic values refer to values of basic Python types (such as booleans, strings, integers, and floats), symbolic objects, or lists, tuples, and dictionaries whose elements are symbolic values. For example, users can pass a lambda function to a symbolic attribute that accepts callable objects. However, using symbolic values for all nodes in a tree provides benefits like symbolic comparison and serialization:

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


# Acceptable.
f = Foo(x=lambda v: v ** 2)
f2 = Foo(x=lambda v: v ** 2)
# Fails: two lambda functions are not equal, even when they share the same definition.
assert pg.eq(f, f2)
# Raises: a lambda function is not serializable by PyGX.
pg.to_json_str(f)


# Recommended.
@pg.symbolize
def square(v):
    return v ** 2


g = Foo(x=square.partial())
g2 = Foo(x=square.partial())
# Succeeds.
assert pg.eq(g, g2)
# Succeeds.
assert pg.from_json_str(pg.to_json_str(g)) == g

Pass-by-value vs. pass-by-reference¶

To ensure that changes made to a symbolic object are reflected in the states of its parent objects, each symbolic object maintains a reference to its parent node. To maintain the single-parent premise, copies must be obtained when a symbolic object is referenced in multiple places. These copies serve as the values for the new references, maintaining a symbolic tree rather than a directed acyclic graph (DAG). This approach simplifies the programming model and ensures that nodes in the symbolic tree are treated as representations rather than program states. When state needs to be shared among copies, the Flyweight pattern can be used.

In contrast to symbolic objects, non-symbolic objects are always passed by reference. For example:

n = node(1)
l = pg.List()

# `n` is used as the first element since it does not have a container yet.
l.append(n)

# `n` is copied and the new value is appended.
l.append(n)

assert n is l[0]
assert n is not l[1]


class X:
    pass


x = X()
# Both appends use `x` as a reference since `X` is not symbolic.
l.append(x)
l.append(x)

assert x is l[0]
assert x is l[1]

Automatic `list`/`dict` conversion¶

A symbolic object may take list-type or dict-type symbolic attributes. For example, in the code above, node.children is a list-type attribute for storing immediate child nodes. In order for PyGX to propagate changes upward along the containing hierarchy, list and dict objects are automatically converted to their symbolic counterparts: pg.List and pg.Dict. For example, tree.children is an instance of pg.List instead of list.

Programming properties¶

Symbolic objects have several useful programming properties. This section demonstrates them by comparing programs with and without symbolic objects.

Symbolic¶

A regular object is created by evaluating its class's __new__ method. Once the evaluation is finished, the binding between the type and values is lost. For example, after the evaluation of Foo(1), the value 1 that was associated with the class Foo in the creation of the object f is no longer accessible:

class Foo:

    def __init__(self, x):
        self._value = x + 1


# The value used for creating `f` is not accessible beyond this point.
f = Foo(1)

In contrast, a symbolic object maintains the binding information throughout its lifetime, which can be accessed through its symbolic attributes. For example, the value of the argument x can be retrieved as a symbolic attribute:

SymbolicFoo = pg.symbolize(Foo)

f = SymbolicFoo(1)

# Returns 1.
f.sym_init_args['x']

"Symbolic" refers to the ability to use the binding information to achieve advanced programming capabilities. This allows a symbolic object to be used for various purposes such as:

Locating a symbolic object within its symbolic tree:
```
print(f.sym_path)
```

Traversing the sub-nodes of a symbolic object:

def visit(path, value, parent):
    print(path, value)

pg.traverse(f, visit)

Printing a symbolic object in human-readable format:
```
print(f)
```

Comparing, hashing, and differentiating symbolic objects based on their representations:

assert pg.eq(f, SymbolicFoo(1))
assert pg.hash(f) == pg.hash(SymbolicFoo(1))
print(pg.diff(f, SymbolicFoo(2)))

Replicating a symbolic object:
```
pg.clone(f)
```

Serializing and deserializing a symbolic object:

json_str = pg.to_json_str(f)
assert pg.eq(f, pg.from_json_str(json_str))

Mutating a symbolic object:
```
f.sym_rebind(x=2)
assert f._value == 3
```

Encoding and decoding a symbolic object relative to a search space:

f_space = SymbolicFoo(pg.oneof([1, 3, 5]))
assert pg.encode(f_space, SymbolicFoo(3)) == pg.DNA(1)
assert pg.materialize(f_space, pg.DNA(1)) == SymbolicFoo(3)

For more operations, see Operations.

Abstract¶

Regular objects are concrete: their arguments must be provided and their values must conform to the constructor's expectations. Symbolic objects, on the other hand, can be abstract, with arguments that may be only partially specified or represented by pure symbolic values (defined by interface pg.PureSymbolic).

For example, foo is a partial object of Foo:

@pg.symbolize
class Foo:

    def __init__(self, x, y):
        self.z = x * y


# `partial` must be called to create a partial object from a symbolic class.
# `foo` is partial since the argument for `y` is not provided.
foo = Foo.partial(x=1)

assert pg.is_partial(foo)
assert pg.is_abstract(foo)

And foo_space is pure symbolic because it is placeheld by pg.oneof:

# `foo_space` is a space of `foo` objects.
foo_space = Foo(pg.oneof([1, 2, 3]), pg.oneof([4, 5]))

assert pg.is_pure_symbolic(foo_space)
assert pg.is_abstract(foo_space)

An abstract symbolic object cannot be evaluated until its missing or placeholder arguments are replaced with concrete values. As such, an abstract symbolic object can only be used for symbolic manipulation and not for evaluation:

# Raises: required argument `y` is missing.
foo.z

foo.sym_rebind(y=2)
# Okay: `y` is now provided, so `foo.z` is computed.
foo.z

# Raises: `foo_space.z` is not yet assigned because `x` and `y`
# are still pure symbolic.
foo_space.z

# Obtain a material `Foo` from the `foo_space`.
foo1 = pg.materialize(foo_space, pg.DNA([0, 1]))

# Okay: `foo1` is bound with x=1, y=5.
foo1.z

Important

Abstract symbolic objects are an essential aspect of symbolic object-oriented programming. They enable the programmer to incorporate high-level descriptions into a program and substitute them with concrete values later. This allows for the creation of domain-specific languages (such as pg.oneof) with ease, making the programming language more extensible and higher-level by separating the expression of ideas (the what) from the implementation of ideas (the how).

See Placeholding for more details about pure symbolic, partial, and abstract objects.

Symbolically validated¶

When a symbolic object is abstract, the call to its __init__ is delayed. Therefore, we cannot depend on user-written validation logic to perform value checks when an abstract object is created. However, the programmer can still catch invalid arguments as soon as the object is created or modified, rather than waiting until the object is evaluated. Symbolic objects are validated based on the rules declared alongside the symbolic fields, which define the acceptable keys and values for symbolic attributes. We call this mechanism symbolic validation. For example, for a regular class that validates its input as follows:

class Foo:

    def __init__(self, x):
        if x < 0:
            raise ValueError('`x` should be non-negative.')
        self.x = x

the symbolic validation rule is defined as:

@pg.symbolize([
    ('x', pg.typing.Int(min_value=0)),
])
class Foo:

    def __init__(self, x):
        self.x = x

Aside from the need to trigger validation on creation and modification, symbolic validation has the following benefits:

It eliminates boilerplate code for argument validation, allowing developers to focus on the core program logic.
The validation rules define both acceptable types and their values, removing the need to document them in the docstring. They describe the rules at a higher abstraction level than equivalent logic in __init__ and are thus more readable (e.g., see the kernel_size_spec below).
The validation rules are reusable across class definitions, so developers can create modular validation rules that are consistent throughout the software system:

def kernel_size_spec():
    """Kernel size is a positive integer or a pair of positive integers."""
    return pg.typing.Union([
        pg.typing.Int(min_value=1),
        pg.typing.Tuple([
            pg.typing.Int(min_value=1),
            pg.typing.Int(min_value=1),
        ]),
    ])


@pg.symbolize([
    ('kernel_size', kernel_size_spec()),
])
def conv2d(kernel_size):
    pass


@pg.symbolize([
    ('pool_size', kernel_size_spec()),
])
def maxpool(pool_size):
    pass

Deeply mutable¶

While regular objects are not mutable, symbolic objects are. For example, we cannot change or even access the bound argument x once foo is created:

class Foo:

    def __init__(self, x):
        self.value = x ** 2


foo = Foo(x=1)

However, we can mutate x with its symbolic counterpart:

SymbolicFoo = pg.symbolize(Foo)

foo = SymbolicFoo(x=1)
assert foo.value == 1

# `foo` will be `SymbolicFoo(2)` after rebinding.
foo.sym_rebind(x=2)

# The internal state is recomputed when the binding information is modified.
assert foo.value == 4

There are two highlights in symbolic objects' mutability:

Strong consistency. Updates to symbolic attributes cause the symbolic object to become invalid, triggering recomputation or adjustment of its internal states. This not only occurs on the modified object itself, but also on the containing objects along the object hierarchy. This is important to ensure that the object and its related objects remain consistent and correct:

@pg.members([
    ('x', pg.typing.Int()),
])
class Foo(pg.Object, sym=True):
    pass


@pg.members([
    ('y', pg.typing.Object(Foo)),
])
class Bar(pg.Object, sym=True):

    def on_sym_ready(self):
        super().on_sym_ready()
        self.z = self.y.x


foo = Foo(1)
bar = Bar(foo)
assert foo.x == 1
assert bar.z == 1

# Manipulation on child symbolic objects causes the parent symbolic
# objects to recompute their internal states.
foo.sym_rebind(x=2)
assert bar.z == 2

Deep manipulability. Given a symbolic object, the user can manipulate not only its immediate children but also the children of its children, and so on. For example:
```
bar.sym_rebind({
    'y.x': 2,
})
assert foo.x == 2
```

Contextual¶

One consequence of the mutability of symbolic objects is that they are also contextual. To maintain consistency of state, changes made to child objects must inform their parent objects to recalculate their state. As a result, each symbolic object has knowledge of its parent and its location within the containing symbolic tree. Users can subscribe to the on_sym_parent_change and on_sym_path_change events to handle context changes:

class ContextAwareFoo(pg.Object, sym=True):

    def on_sym_parent_change(self, old_parent, new_parent):
        super().on_sym_parent_change(old_parent, new_parent)
        print('Parent has changed', old_parent, new_parent)

    def on_sym_path_change(self, old_path, new_path):
        super().on_sym_path_change(old_path, new_path)
        print('Location has changed', old_path, new_path)


f = ContextAwareFoo()
# `f.on_sym_parent_change` is triggered: from None to `x`;
# `f.on_sym_path_change` is also triggered: from '' to 'a'.
x = pg.Dict(a=f)

# `f.on_sym_path_change` is triggered: from 'a' to '[0].a'.
y = pg.List([x])

# `f.on_sym_parent_change` is triggered: from `x` to None;
# `f.on_sym_path_change` is also triggered: from 'a' to ''.
x.clear()

See Events for more details.

Better software design¶

Using symbolic objects leads to a more object-oriented software design and better utilizes the composability of reusable building blocks.

More object-oriented¶

PyGX promotes the use of symbolic functions — classes that align the programming style between classes and functions, resulting in more consistent object bindings:

@pg.symbolize
def bar(y):
    return y ** 2


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


Foo(1, bar(2))

Better compositionality¶

The use of symbolic objects leads to more hierarchical bindings, which enables the creation of large-scale compositions using smaller, reusable building blocks.

Functions use arguments to customize the behavior defined in the function body, which often calls other functions. Therefore, when we need to control the behaviors at deeper levels, we need to pass down the arguments across the call hierarchy (ignoring globals in this analysis as it is not best practice). For example, in order to customize bar's behavior inside foo, y needs to be passed down through foo:

def foo(x, y):
    return x + bar(y)

If we need to further control the function called within foo, we modify the signature of foo as follows:

def foo(x, bar_fn, y):
    return x + bar_fn(y)

This leads to a flat binding. For a program that uses functions extensively, flat bindings can lead to a long argument list at outer scopes. As a result, the program becomes either less reusable (with a short argument list) or less usable (with a long argument list).

However, with classes the program bindings become hierarchical, which allows a large number of binding parameters to be specified in semantic groups without sacrificing usability:

def foo(x, bar):
    return bar()


class Bar:

    def __init__(self, y):
        self.y = y

    def __call__(self):
        return self.y


foo(x, Bar(y))