Subgraph Netlist Decorator

class hal_py.SubgraphNetlistDecorator

A netlist decorator that operates on an existing subgraph of the associated netlist to, e.g., copy the subgraph as a new netlist object or compute a Boolean function describing the subgraph.

__init__(self: hal_py.SubgraphNetlistDecorator, netlist: hal_py.Netlist) → None

Construct new SubgraphNetlistDecorator object.

Parameters: netlist (hal_py.Netlist) – The netlist to operate on.

copy_subgraph_netlist(*args, **kwargs)

Overloaded function.

copy_subgraph_netlist(self: hal_py.SubgraphNetlistDecorator, subgraph_gates: List[hal_py.Gate], all_global_io: bool = False) -> hal_py.Netlist

Get a deep copy of a netlist subgraph including all of its gates and nets, but excluding modules and groupings.

param list[hal_py.Gate] subgraph_gates

The gates making up the subgraph that shall be copied from the netlist.

param bool all_global_io

Set True to mark all nets as global input or output that lost at least one source or destination in the copied netlist, False to only mark them if all sources or destinations were removed. Global inputs and outputs of the parent netlist will always also be annotated as global inputs or outputs. Defaults to False.

returns

The copied subgraph netlist on success, None otherwise.

rtype

hal_py.Netlist or None
copy_subgraph_netlist(self: hal_py.SubgraphNetlistDecorator, subgraph_module: hal_py.Module, all_global_io: bool = False) -> hal_py.Netlist

Get a deep copy of a netlist subgraph including all of its gates and nets, but excluding modules and groupings.

param hal_py.Module subgraph_module

The module making up the subgraph that shall be copied from the netlist, including the gates of all of its submodules.

param bool all_global_io

Set True to mark all nets as global input or output that lost at least one source or destination in the copied netlist, False to only mark them if all sources or destinations were removed. Global inputs and outputs of the parent netlist will always also be annotated as global inputs or outputs. Defaults to False.

returns

The copied subgraph netlist on success, None otherwise.

rtype

hal_py.Netlist or None

get_subgraph_function(*args, **kwargs)

Overloaded function.

get_subgraph_function(self: hal_py.SubgraphNetlistDecorator, subgraph_gates: List[hal_py.Gate], subgraph_output: hal_py.Net) -> Optional[hal_py.BooleanFunction]

Get the combined Boolean function of a subgraph starting at the source of the provided subgraph output net. The function is composed backwards through the gates of the subgraph. A gate is composed into it only if its gate type is combinational and it has a Boolean function for the output pin that the walk reaches it through. At any other gate, at a gate outside of the subgraph, at a net without a source, and at a global input net, the walk stops and the net becomes a variable of the function. Hence, flip-flops, memories, and gates without a Boolean function bound the subgraph function even if they are part of the subgraph_gates. If the Boolean function of a gate cannot be built in terms of nets, e.g., because one of its input pins has no net or a gate parameter it depends on has no value, a warning is logged and the walk stops at that gate as well. The variables of the resulting Boolean function are created from the subgraph input nets using BooleanFunctionNetDecorator.get_boolean_variable. For repeated calls on the same subgraph, create a cache with make_subgraph_function_cache and pass it to get_subgraph_function instead.

param list[hal_py.Gate] subgraph_gates

The gates making up the subgraph to consider.

param hal_py.Net subgraph_output

The subgraph output net for which to generate the Boolean function.

returns

The combined Boolean function of the subgraph on success, None otherwise.

rtype

hal_py.BooleanFunction or None
get_subgraph_function(self: hal_py.SubgraphNetlistDecorator, subgraph_module: hal_py.Module, subgraph_output: hal_py.Net) -> Optional[hal_py.BooleanFunction]

Get the combined Boolean function of a subgraph starting at the source of the provided subgraph output net. The function is composed backwards through the gates of the subgraph. A gate is composed into it only if its gate type is combinational and it has a Boolean function for the output pin that the walk reaches it through. At any other gate, at a gate outside of the subgraph, at a net without a source, and at a global input net, the walk stops and the net becomes a variable of the function. Hence, flip-flops, memories, and gates without a Boolean function bound the subgraph function even if they are part of the subgraph_module. If the Boolean function of a gate cannot be built in terms of nets, e.g., because one of its input pins has no net or a gate parameter it depends on has no value, a warning is logged and the walk stops at that gate as well. The variables of the resulting Boolean function are created from the subgraph input nets using BooleanFunctionNetDecorator.get_boolean_variable. For repeated calls on the same subgraph, create a cache with make_subgraph_function_cache and pass it to get_subgraph_function instead.

param hal_py.Module subgraph_module

The module making up the subgraph to consider, including the gates of all of its submodules.

param hal_py.Net subgraph_output

The subgraph output net for which to generate the Boolean function.

returns

The combined Boolean function of the subgraph on success, None otherwise.

rtype

hal_py.BooleanFunction or None
get_subgraph_function(self: hal_py.SubgraphNetlistDecorator, subgraph_output: hal_py.Net, cache: hal_py.SubgraphFunctionCache) -> Optional[hal_py.BooleanFunction]

Get the combined Boolean function of the subgraph of the cache starting at the source of the provided subgraph output net. The function is composed backwards through the gates of the subgraph. A gate is composed into it only if its gate type is combinational and it has a Boolean function for the output pin that the walk reaches it through. At any other gate, at a gate outside of the subgraph, at a net without a source, and at a global input net, the walk stops and the net becomes a variable of the function. Hence, flip-flops, memories, and gates without a Boolean function bound the subgraph function even if they are part of the subgraph of the cache. If the Boolean function of a gate cannot be built in terms of nets, e.g., because one of its input pins has no net or a gate parameter it depends on has no value, a warning is logged and the walk stops at that gate as well. The variables of the resulting Boolean function are created from the subgraph input nets using BooleanFunctionNetDecorator.get_boolean_variable. The Boolean functions computed for the gate outputs of the subgraph are stored in the cache, and those stored by earlier calls are reused instead of being computed again. The cache must have been created for the netlist of this decorator.

param hal_py.Net subgraph_output

The subgraph output net for which to generate the Boolean function.

param hal_py.SubgraphFunctionCache cache

The cache holding the subgraph and the Boolean functions computed for it.

returns

The combined Boolean function of the subgraph on success, None otherwise.

rtype

hal_py.BooleanFunction or None

get_subgraph_function_inputs(*args, **kwargs)

Overloaded function.

get_subgraph_function_inputs(self: hal_py.SubgraphNetlistDecorator, subgraph_gates: List[hal_py.Gate], subgraph_output: hal_py.Net) -> Optional[Set[hal_py.Net]]

Get the inputs of the combined Boolean function of a subgraph starting at the source of the provided subgraph output net. This does not actually build the Boolean function but only determines the inputs the subgraph function would have, which is a lot faster. The subgraph is traversed backwards through its gates. A gate is traversed only if its gate type is combinational and it has a Boolean function for the output pin that the walk reaches it through. At any other gate, at a gate outside of the subgraph, at a net without a source, and at a global input net, the walk stops and the net becomes an input of the function. Hence, flip-flops, memories, and gates without a Boolean function bound the subgraph function even if they are part of the subgraph_gates. If the Boolean function of a gate cannot be built in terms of nets, e.g., because one of its input pins has no net or a gate parameter it depends on has no value, a warning is logged and the walk stops at that gate as well. For repeated calls on the same subgraph, create a cache with make_subgraph_function_cache and pass it to get_subgraph_function_inputs instead.

param list[hal_py.Gate] subgraph_gates

The gates making up the subgraph to consider.

param hal_py.Net subgraph_output

The subgraph output net from which to start the back propagation.

returns

The input nets that would be the input for the subgraph function on success, None otherwise.

rtype

set(hal_py.Net) or None
get_subgraph_function_inputs(self: hal_py.SubgraphNetlistDecorator, subgraph_module: hal_py.Module, subgraph_output: hal_py.Net) -> Optional[Set[hal_py.Net]]

Get the inputs of the combined Boolean function of a subgraph starting at the source of the provided subgraph output net. This does not actually build the Boolean function but only determines the inputs the subgraph function would have, which is a lot faster. The subgraph is traversed backwards through its gates. A gate is traversed only if its gate type is combinational and it has a Boolean function for the output pin that the walk reaches it through. At any other gate, at a gate outside of the subgraph, at a net without a source, and at a global input net, the walk stops and the net becomes an input of the function. Hence, flip-flops, memories, and gates without a Boolean function bound the subgraph function even if they are part of the subgraph_module. If the Boolean function of a gate cannot be built in terms of nets, e.g., because one of its input pins has no net or a gate parameter it depends on has no value, a warning is logged and the walk stops at that gate as well. For repeated calls on the same subgraph, create a cache with make_subgraph_function_cache and pass it to get_subgraph_function_inputs instead.

param hal_py.Module subgraph_module

The module making up the subgraph to consider, including the gates of all of its submodules.

param hal_py.Net subgraph_output

The subgraph output net from which to start the back propagation.

returns

The input nets that would be the input for the subgraph function on success, None otherwise.

rtype

set(hal_py.Net) or None
get_subgraph_function_inputs(self: hal_py.SubgraphNetlistDecorator, subgraph_output: hal_py.Net, cache: hal_py.SubgraphFunctionCache) -> Optional[Set[hal_py.Net]]

Get the inputs of the combined Boolean function of the subgraph of the cache starting at the source of the provided subgraph output net. This does not actually build the Boolean function but only determines the inputs the subgraph function would have, which is a lot faster. The subgraph is traversed backwards through its gates. A gate is traversed only if its gate type is combinational and it has a Boolean function for the output pin that the walk reaches it through. At any other gate, at a gate outside of the subgraph, at a net without a source, and at a global input net, the walk stops and the net becomes an input of the function. Hence, flip-flops, memories, and gates without a Boolean function bound the subgraph function even if they are part of the subgraph of the cache. If the Boolean function of a gate cannot be built in terms of nets, e.g., because one of its input pins has no net or a gate parameter it depends on has no value, a warning is logged and the walk stops at that gate as well. The inputs determined for the gate outputs of the subgraph are stored in the cache, and those stored by earlier calls are reused instead of being determined again. The cache must have been created for the netlist of this decorator.

param hal_py.Net subgraph_output

The subgraph output net from which to start the back propagation.

param hal_py.SubgraphFunctionCache cache

The cache holding the subgraph and the inputs determined for it.

returns

The input nets that would be the input for the subgraph function on success, None otherwise.

rtype

set(hal_py.Net) or None

make_subgraph_function_cache(*args, **kwargs)

Overloaded function.

make_subgraph_function_cache(self: hal_py.SubgraphNetlistDecorator, subgraph_gates: List[hal_py.Gate]) -> object

Create a cache for one specific subgraph, to be passed to get_subgraph_function or get_subgraph_function_inputs in place of the subgraph. The cache shares the Boolean functions and inputs computed for the gate outputs of the subgraph across calls, so that logic which several subgraph output nets have in common is traversed only once. The cache belongs to the netlist of this decorator and must be dropped when the netlist is modified. It keeps this decorator and its netlist alive.

param list[hal_py.Gate] subgraph_gates

The gates making up the subgraph to consider.

returns

The cache on success, None otherwise.

rtype

hal_py.SubgraphFunctionCache or None
make_subgraph_function_cache(self: hal_py.SubgraphNetlistDecorator, subgraph_module: hal_py.Module) -> object

Create a cache for one specific subgraph, to be passed to get_subgraph_function or get_subgraph_function_inputs in place of the subgraph. The cache shares the Boolean functions and inputs computed for the gate outputs of the subgraph across calls, so that logic which several subgraph output nets have in common is traversed only once. The cache belongs to the netlist of this decorator and must be dropped when the netlist is modified. It keeps this decorator and its netlist alive.

param hal_py.Module subgraph_module

The module making up the subgraph to consider, including the gates of all of its submodules.

returns

The cache on success, None otherwise.

rtype

hal_py.SubgraphFunctionCache or None

class hal_py.SubgraphFunctionCache

A reusable store for the Boolean functions that SubgraphNetlistDecorator.get_subgraph_function computes and the inputs that SubgraphNetlistDecorator.get_subgraph_function_inputs determines for the output pins of the gates of one specific subgraph.

The subgraph a cache belongs to is sealed in when it is created and the cache can only ever be used for exactly that subgraph. Create one with SubgraphNetlistDecorator.make_subgraph_function_cache and drop it when the netlist is modified.

__len__(self: hal_py.SubgraphFunctionCache) → int

Get the number of cached Boolean functions.

Returns: The number of cached Boolean functions.
Return type: int