Skip to content

DSG API Reference#

adsg_core.graph.adsg_basic.BasicDSG(*args, start_nodes=None, **kwargs) #

Implementation of the DSG with some helper functions:

  • add_edge and add_edges for adding nodes and edges to the graph
  • add_selection_choice for adding edges representing a selection choice
  • add_connection_choice for adding edges representing a connection choice
  • set_start_nodes for setting the nodes where derivation starts

It is recommended to use these helper functions to build and initialize the graph:

  1. Add edges and choices (add_edge, add_edges, add_selection_choice, add_connection_choice)
  2. Set start nodes (set_start_nodes)
  3. Initialize choices (initialize_choices)

des_var_nodes: List[DesignVariableNode] property #

Get all non-constrained (non-linked) design variable nodes in the graph

feasible property #

Whether the architecture is feasible or not (unconnectable connectors and/or unsolvable incompatibilities)

final property #

Whether the architecture is final (no more choices to make) or not

graph property #

The underlying networkx directed graph

add_connection_choice(choice_id: str, src_nodes: ConnNodes, tgt_nodes: ConnNodes, exclude: List[Tuple[ConnectorNode, ConnectorNode]] = None, derive_tgt_nodes: bool = False) -> ConnectionChoiceNode #

A connection choice is a choice on how to connect one or more source nodes to one or more target nodes. Each connector node can place constraints on the accepted connection degree: one or more specific numbers, a range, or a lower limit. Additionally, repeated connections between the same nodes can be allowed or not.

To model the non-influence of connection order, connector nodes can be grouped by a ConnectorDegreeGroupingNode, which as connection degree will have the sum of the connection degrees from underlying nodes, depending on whether they exist in an architecture or not.

Optionally, the target nodes can be derived by the source nodes.

add_edge(src: DSGNode, tgt: DSGNode, edge_type: EdgeType = EdgeType.DERIVES) #

Add a directed edge between some source and target nodes

add_edges(edges: List[Tuple[DSGNode, DSGNode]], edge_type: EdgeType = EdgeType.DERIVES) #

Add multiple edges at a time

add_incompatibility_constraint(nodes: List[DSGNode], **attr) #

An incompatibility constraint defines that two nodes cannot exist in an architecture at the same time. This means that when one of the nodes becomes confirmed by making a choice, the other node (and its derived nodes) will be removed from the graph. If both of the nodes are confirmed, it means that there is no way to have only one of them in an architecture, and that therefore the architecture is infeasible (this can also happen before any choices have been made!).

Incompatibility constraints should be added before initializing the graph's choices.

add_node(node: DSGNode) #

Add a single node to the graph. Note that it will be removed if it is not set as a start node, or connected to it (through a derivation edge) at some point

add_selection_choice(choice_id: str, originating_node: DSGNode, option_nodes: List[DSGNode], is_ordinal=False) -> SelectionChoiceNode #

A selection choice is a choice between one or more mutually-exclusive option nodes. When choosing one of the options, the choice node is removed, and the originating node is connected to the chosen option node.

Set is_ordinal=True if there is inherent ordering between the available options.

constrain_choices(constraint: ChoiceConstraintType, choice_nodes: List[CDVNode], remove_infeasible_choices=True) -> DSG #

Create a new choice constraint (see ChoiceConstraintType). For design variable nodes, only the LINKED constraint is available.

Following constraints are available (ChoiceConstraintType):

  • LINKED: To make all choices have the same option index --> AA, BB, CC
  • PERMUTATION: To make the choices be permutations of option indices --> AB, BA, AC, CA, BC, CB
  • UNORDERED: To have all option index combinations without ordering --> AA, AB, AC, BB, BC, CC
  • UNORDERED_NOREPL: Same but also without replacement --> AB, AC, BC

copy() #

Create a copy of the DSG

derived_nodes(node) #

Get all nodes derived by this node

derives(source_node: DSGNode, target_node: DSGNode, connects=False) #

Check whether the source node derives the target node (i.e. whether there is a path along derivation edges from source to target). If connects is set to True, also connection edges can be part of a path.

des_var_value(des_var_node: DesignVariableNode) -> Optional[Union[float, int]] #

Get the value of a design variable node. If not set, returns None. For discrete design variables, the index of the selected option is returned.

export_dot(path=None, return_dot=False) #

Export to DOT (use Graphviz / https://viz-js.com/ to view)

export_drawio(path=None) #

Export to draw.io

export_gml(path=None) #

Export to GML (use e.g. Gephi to view)

get_for_apply_connection_choice(choice_node: ConnectionChoiceNode, edges: Sequence[Tuple[ConnectorNode, ConnectorNode]] = None, validate=True) #

Get a new DSG where the connection choice has the provided connection edges applied

get_for_apply_selection_choice(choice_node, target_option_node) #

Get a new DSG where the selection choice has been applied with the provided target option node

get_nodes_by_subtype(type_) #

Get all nodes in the graph that are or inherit from the given type

get_option_nodes(choice_node: SelectionChoiceNode) #

Get a list of option nodes available for a selection choice

get_ordered_next_choice_nodes() -> List[ChoiceNode] #

Get the next (selection or connection) choice node(s) that are active and can be applied

initialize_choices() #

Initializes choice nodes and makes the DSG ready for use in deriving architecture instances: - Removes nodes that are incompatible with any of the initially-confirmed nodes - Sets the influence matrix, needed for determining choice order - Resolves initially-active choices with 0 or 1 options

iter_possible_connection_edges(choice_node: ConnectionChoiceNode) #

Iterate over possible sets of connection edges for this connection choice

next(node, edge_type: EdgeType = None) #

Iterate over outgoing nodes, optionally filtering by edge type

prev(node, edge_type: EdgeType = None) #

Iterate over incoming nodes, optionally filtering by edge type

render(title=None, print_svg=False, print_dot=False) #

Render the DSG as a graph. Open a webbrowser, or renders it as cell output if used in an IPython/Jupyter notebook.

render_all(idx=None, title=None, print_svg=False, print_dot=False) #

Renders all DSG instances as a graph (optionally provide only specific indices to render). Open a webbrowser, or renders it as cell output if used in an IPython/Jupyter notebook.

set_des_var_value(des_var_node: DesignVariableNode, value: Union[float, int]) #

Set the value of a design variable node. Discrete values are defined as an option index (so not the value of an option itself).

set_start_nodes(start_nodes: Set[DSGNode] = None, initialize_choices=True) #

Defines which nodes should be used for starting the existence derivations. If not explicitly defined, uses all nodes with no incoming edges.

Nodes that cannot be derived from any of the starting nodes are removed from the graph.

adsg_core.graph.adsg_nodes.DSGNode(obj_id=None, decision_id=None, option_id=None, src_decision_link_key=None, tgt_decision_link_key=None, perm_decision_link_key=None, obj_ref=None) #

Base class for any node used in the DSG.

The decision_id attribute is used for grouping nodes into selection-choices to be taken. The option_id attribute is used for sorting choice options (if applicable).

copy_node(i=None) #

Copy the node without reference

get_export_title() -> str #

Human-readable title for exporting

str_context() #

Technical title for exporting

adsg_core.graph.adsg_nodes.NamedNode(name: str, **kwargs) #

Generic node with a name

adsg_core.graph.adsg_nodes.ConnectorNode(name: str = None, deg_spec=None, deg_list=None, deg_min=1, deg_max=None, repeated_allowed=False, remove_if_unconnected=False, **kwargs) #

A node specifying some connection to be made. Specifies data about the number of connections possible using the deg_list attribute (specifying a list of allowed number of connections), or using the deg_min and deg_max attributes, which specify a range (inclusive). Note that deg_max can also be inf (math.inf), denoting no upper limit.

The repeated_allowed flag determines whether the connector node accepts parallel (i.e. repeated) edges.

The remove_if_unconnected flag determines that the connector node should be removed from the graph if it is left unconnected. In practice this means that the DSG is modified to have a selection choice to select whether the connector node is included, before the connection choice is resolved.

is_valid(degree) #

Check whether the given connection degree is valid for the connection constraint

adsg_core.graph.adsg_nodes.ConnectorDegreeGroupingNode(name: str = None) #

Groups a bunch of connectors. Used when the connection order of the connectors does not matter. This means that this class only looks at the aggregate number of connections accepted by the grouped connectors. The update_deg function should be called with the grouped nodes to update the connection degree specifications.

adsg_core.graph.adsg_nodes.DesignVariableNode(name, bounds=None, options=None, idx=None, is_ordinal=False, **kwargs) #

Node representing a design variable.

Set is_ordinal=True if there is inherent ordering between the available options.

is_discrete property #

Whether the design variable is discrete or continuous

correct_value(value) #

Ensure a value is within the bounds or represents a valid option

adsg_core.graph.adsg_nodes.MetricNode(name, direction: int = None, ref: float = None, idx=None, type_=None) #

Node representing a performance metric. In the end, a performance metric can either be used as an objective or as a constraint in an optimization problem.

If a direction (meaning which direction of the value is "better") is given, it can be used an objective. If also a reference is given (meaning it should be in a specified direction, but at least this value), it can also be used as a constraint.

Metric type is derived automatically, however to force the type you can supply a MetricType:

  • NONE: no role in the optimization problem
  • OBJECTIVE: metric is an objective (provide a direction)
  • CONSTRAINT: metric is a constraint (provide a direction and a reference value)

adsg_core.graph.adsg_nodes.SelectionChoiceNode(decision_id=None, decision_sort_key=None, is_ordinal=False) #

Node representing a selection: a choice with a discrete set of mutually exclusive options to choose from.

Set is_ordinal=True if there is inherent ordering between the available options.

adsg_core.graph.adsg_nodes.ConnectionChoiceNode(decision_id=None, decision_sort_key=None) #

Node representing a connection choice: a choice about how to connect between a set of source nodes and a set of target nodes. Sources and targets should be ConnectorNode types.