Welcome to KADMOS’s documentation! — KADMOS 0.9.0 documentation

# Welcome to KADMOS’s documentation!

See sidebar on the right for the table of contents.

- Index
- Module Index
- Search Page

# Documentation for the Code

Below the simplified class diagram of the KADMOS package is shown (not all methods are included for clarity). The UML can als be downloaded as PDF `here`.

Example scripts for using KADMOS are available in the examples/scripts folder. The following scripts are available there:

- `Sellar Problem`: Small two-disciplinary analytical MDO problem based on MDO literature.
- `Super-sonic Business Jet`: The jet design is decribed at http://ntrs.nasa.gov/archive/nasa/casi.ntrs.nasa.gov/19980234657.pdf and was implemented in Python for OpenMDAO by Sylvain Dubreuil and Remi Lafage of ONERA, the French Aerospace Lab.
- `TU Delft Wing Design`: The wing design case described here was developed at TU Delft and takes a variety of different disciplines into account.

## Graph

Below the KADMOS KadmosGraph class and its subclasses are listed.

### KadmosGraph

class `kadmos.graph.graph_kadmos.` `KadmosGraph`(*args, **kwargs)
  `add_contact`(name, email, uid, company=None, department=None, function=None, address=None, telephone=None, country=None, roles=None)

    Method to add a contact to the graph organization.

    Parameters: | name (str) – name of the contact email (str) – email adress of the contact uid (str) – uid of the contact company (str) – company of which the contact is an employee, optional department (str) – department of company that the contact works at, optional function (str) – the function of the contact, optional address (str) – company address, optional telephone (int) – telephone number of the contact, optional country (str) – country of company, optional roles – organizational role(s) of contact within the project, optional
    Type: | str, list

    Optional organizational contact roles:

    - ‘architect’
    - ‘integrator’
    - ‘collaborativeEngineer’
    - ‘toolSpecialist’
    - ‘customer’

    Adding a contact with one organizational role:

        >>> add_contact('Maaike de Wit', 'M.D.deWit@student.tudelft.nl', 'mddewit', company='TU Delft',
        >>>             roles='integrator')

    Adding a contact with two (or more) organizational roles:

        >>> roles = ['integrator', 'architect']
        >>> add_contact('Maaike de Wit', 'M.D.deWit@student.tudelft.nl', 'mddewit', company='TU Delft', roles=roles)

    Note

    In case the contact uid already exists the old contact attributes are conserved and only new roles are added to the roles already present for that contact. To change old contact information, this has to be adjusted in the XML-file from which the old contact information is loaded.

    Hint

    To add (more) roles to the existing contact, it is recommended to use the method: add_contact_roles()

  `add_contact_roles`(uid, roles)

    Method to add roles to existing contacts

    Parameters: | uid (str) – uid of the contact roles (str, list) – organizational role(s) to be added to the existing contact

    Optional organizational contact roles:

    - ‘architect’
    - ‘integrator’
    - ‘collaborativeEngineer’
    - ‘toolSpecialist’
    - ‘customer’

    Adding an organizational role to an existing contact:

        >>> graph.add_contact('mddewit', roles='integrator')

    Adding two (or more) organizational roles to an existing contact:

        >>> roles = ['integrator', 'architect']
        >>> graph.add_contact('mddewit', company='TU Delft', roles=roles)

    Hint

    This method only works for existing contacts. To add a contact use the method: add_contact()

  `add_dc_execution_details`(dc_uid, operating_system=None, integration_platform=None, command=None, description=None, software_requirements=None, hardware_requirements=None, replace_for=None)

    Method to add execution details information to a design competence

    Parameters: | dc_uid (str) – uid of the design competence operating_system (str) – Operating system the tool is running on (e.g. Linux, Windows, MAC OS), optional integration_platform (str) – Specification of the integration platform (e.g. RCE, Optimus), optional command (str) – Execution command (e.g. runTool.exe), optional description (str) – Additional infos of the execution, optional software_requirements (str) – Requirements on the software side, optional hardware_requirements (int) – Requirements on the hardware side, optional replace_for – Index of execution details to be replaced

  `add_dc_general_info`(dc_uid, description, status=None, creation_date=None, owner_uid=None, creator_uid=None, operator_uid=None, model_definition=None)

    Method to add general info to a design competence

    Parameters: | dc_uid (str) – uid of the design competence description (str) – description of the design competence status (str) – status of the design competence, optional creation_date (date) – creation date of the design competence, optional owner_uid (str) – uid of the owner of the design competence, optional creator_uid (str) – uid of the creator of the design competence, optional operator_uid (str) – uid of the operator of the design competence, optional model_definition (str) – model definition of the design competence, optional

  `add_dc_licensing`(dc_uid, license_type=None, license_specification=None, license_info=None)

    Method to add licensing information to a design competence

    Parameters: | dc_uid (str) – uid of the design competence license_type (str) – type of the license, optional license_specification (str) – specification of the license, optional license_info (str) – additional info about the license, optional

  `add_dc_performance_info`(dc_uid, precision=None, fidelity_level=None, run_time=None, verification=None)

    Method to add performance information to a design competence

    Parameters: | dc_uid (str) – uid of the design competence precision (float) – precision of the design competence, optional fidelity_level (int) – the level of fidelity of the design competence, optional run_time (float) – the run time of the design competence, optional verification (dict) – verification method of the design competence, optional

    At least one of the optional elements for the performance information has to be defined.

    Adding performance info with a verification:

        >>> verification = {'method': 'dummy_method', 'verifier': contact_uid, 'result': 'dummy_result',
        >>>                 'date': dateTime, 'version': dummy_version}
        >>> graph.add_dc_performance_info(dc_uid, verification=verification)

  `add_dc_remote_component_info`(dc_uid, single_or_multi_execution, job_name, remote_engineer, notification_message, data_exchange_dict=None)

    Method to add execution information to a design competence

    Parameters: | dc_uid (str) – uid of the design competence single_or_multi_execution (str) – execution type. Choose from ‘single’ or ‘multiple’. job_name (str) – job name of the design competence remote_engineer (str) – contact uid of remote engineering of the design competence notification_message (str) – message to notify remote_engineer data_exchange_dict (str) – data exchange settings of the design competence

    Example use:

        >>> single_or_multi = "single"
        >>> job_name = 'job_{}'.format(fpg.nodes[node]['label'].replace(' ', ''))
        >>> notification_message = 'Hi, could you please run this tool {} for me for my {} AGILE workflow '
        >>>                        'execution. Thanks.'.format(fpg.nodes[node]['label'].replace(' ', ''), architecture)
        >>> fpg.add_dc_remote_component_info(node, single_or_multi, job_name, 'ivangent', notification_message,
        >>>                                  data_exchange_dict={'urlsite': 'some_url',
        >>>                                                      'folder': 'some_folder'})

  `add_dc_sources`(dc_uid, repository_link=None, download_link=None, references=None)

    Method to add source information to a design competence

    Parameters: | dc_uid (str) – uid of the design competence repository_link (str) – link to the dc’s repository, optional download_link (str) – link to download the dc, optional references (list) – additional references, optional

  `add_default_description`()

    Method to add a default description attribute to a graph

    Returns: | graph with default attribute description
    Return type: | KadmosGraph

  `add_default_name`()

    Method to add a default name attribute to a graph

    Returns: | graph with default attribute name
    Return type: | KadmosGraph

  `add_edge`(u, v, attr_dict=None, **attr)

    Add an edge between u and v.

    Parameters: | u (can be, for example, strings or numbers. Nodes must be hashable (and not None) Python objects.) – node v (see u) – node attr_dict (str) – keyword arguments attr (str) – edge data (or labels or objects) can be assigned using keyword arguments.

    The nodes u and v will be automatically added if they are not already in the graph.

    Adding an existing edge results in an update of the edge data.

    Edge attributes can be specified with keywords or by directly accessing the edge’s attribute dictionary. See examples below.

    The following examples both add the edge e=(1,2) to graph G:

        >>> G = nx.Graph() # or DiGraph, MultiGraph, MultiDiGraph, etc
        >>> e = (1, 2)
        >>> G.add_edge(1, 2) # explicit two-node form
        >>> G.add_edge(*e) # single edge as tuple of two nodes

    Many NetworkX algorithms designed for weighted graphs use an edge attribute (by default ‘weight’) to hold a numerical value. Associate date to edge using keywords:

        >>> G.add_edge(1, 2, weight=3)
        >>> G.add_edge(1, 3, weight=7, capacity=15, length=342.7)

    For non-string attribute keys, use subscript notation.

        >>> G.add_edge(1, 2)
        >>> G[1][2}.update({0: 5})
        >>> G.edges[1, 2].update({0: 5})

  `add_function_instance`(node, serves, instance=None)

    Method to change the instance of a node

    Parameters: | node (str) – node to change the instance of serves (list) – list of nodes for which the new instances should provide inputs instance (int) – new instance, optional (default=None)

    In case the default is used the instance added is the highest current instance + 1.

  `add_instance`(node, instance=None)

    Method to change the instance of a node

    Parameters: | node (str) – node to change the instance of instance (int) – new instance, optional (default=None)

    In case the default is used the instance added is the highest current instance + 1.

  `add_instance_of`(file_path, node)

    Method to duplicate a function with a higher instance

    Parameters: | file_path (basestring) – path to CMDOWS file node (str) – node to get instance of
    Returns: | new node
    Return type: | str

  `add_node`(n, attr_dict=None, **attr)

    Add a single node and update node attributes.

    Parameters: | n (A node can be any hashable Python object except None.) – node attr_dict (dict) – dictionary of attribute keyword arguments. attr (str, dict) – Set or change node attributes using attr_dict.

    Examples:

        >>> G = nx.Graph()   # or DiGraph, MultiGraph, MultiDiGraph, etc
        >>> G.add_node(1)
        >>> G.add_node('Hello')
        >>> K3 = nx.Graph([(0, 1), (1, 2), (2, 0)])
        >>> G.add_node(K3)
        >>> G.number_of_nodes()

    Use keywords set/change node attributes:

        >>> G.add_node(1, size=10)
        >>> G.add_node(3, weight=0.4, UTM=('13S', 382871, 3972649))

    Note

    A hashable object is one that can be used as a key in a Python dictionary. This includes strings, numbers, tuples of strings and numbers, etc.

    Note

    On many platforms hashable items also include mutables such as NetworkX Graphs, though one should be careful that the hash doesn’t change on mutables.

  `add_objective_function_by_nodes`(*args, **kwargs)

    This function adds objective functions to the graph using lists of variable nodes.

    Parameters: | args (list) – list of nodes (list elements must be strings) kwargs (list) – list of nodes (list elements must be strings)
    Returns: | list of Objective Functions added to Graph
    Return type: | list

    Each list produces a separate objective function node in the graph. If the list if passed as a keyword argument, the keyword is taken as the name of the objective function node. Otherwise, a standard name will be given to the node. Each objective function node has one output variable, and takes the nodes given in the argument list as input nodes.

    If the provided nodes do not exist in the graph, a warning is given to the user on whether to continue the addition of the objective function to the graph using valid nodes.

    Example:

        >>> unnamed_function = list(>>list of graph nodes<<)
        >>> named_obj_fcn = list(>>list of graph nodes<<)
        >>> MyGraph.add_objective_function_by_nodes(unnamed_function, My_obj_fcn_name = named_obj_fcn)

    The added objective function nodes can be queried by the attribute:

        >>> Graph.nodes[node]["name"] == "Objective"

  `change_graph_class`(graph_class)

    Method to adjust the class of a graph.

    Returns: | newly classed graph.
    Return type: | graph_class

  `check`(raise_error=False)

    Method to check the graph for validity and completeness.

    Parameters: | raise_error (bool) – determines if an error should be raised in case of an invalid graph
    Returns: | result of the check
    Return type: | bool

    Note

    Several checks are performed. However the method does not guarantee the validity of the graph.

    The checks are split into several categories and the methods _check_category_a, _check_category_b and _check_category_c are used to determine the overall validity and completeness. These sub methods are generally defined below and are then further refined in child classes.

  `check_cmdows_integrity`(convention=True, mpg=None)

    Method to check the integrity of the CMDOWS file that can be created with the save method.

    Parameters: | convention (bool) – option for applying a UID convention mpg (MdaoProcessGraph) – MPG to be saved together with graph
    Returns: | check result
    Return type: | bool

    The integrity check is graph specific and thus needs to be executed for every graph before saving as CMDOWS if one wants to be sure that the CMDOWS file is integer. Due to its relative long runtime this check is however not performed automatically when using the save method.

  `check_for_coupling`(function_order, only_feedback=False, raise_error_if_true=False)

    Function to check for the presence of coupling in a graph for a list of analyses in a given analysis order.

    Parameters: | function_order (list) – list with node names of functions only_feedback (bool) – Boolean on whether to check for feedback coupling only (this is useful for Gauss-Seidel) raise_error_if_true (bool) – Boolean on whether to raise an error if coupling exists
    Returns: | Boolean value on whether coupling exists
    Return type: | bool

    Note

    only the functions in the function_order list are checked for feedback.

  `copy_as`(graph_class, as_view=False)

    Method to make a copy of a graph and make it into another KADMOS graph class.

    Returns: | copy of the graph
    Return type: | KadmosGraph

  `copy_edge`(old_edge, new_edge)

    Method to copy an edge so that attributes of the old edge are maintained.

    Parameters: | old_edge (tuple) – edge to be copied new_edge (tuple) – edge to be created
    Returns: | created edge
    Return type: | tuple

  `copy_node_with_suffix`(node, suffix, label_extension, attr_dict=None, **kwargs)

    Method to simply copy a node and its attributes by creating a new node with a suffix.

    Parameters: | node (str) – node to be copied suffix (str) – suffix to be added to the node ID label_extension (str) – extension for labels kwargs (dict, int) – keyword arguments will be added as node attributes
    Returns: | new node and enriched graph
    Return type: | str

  `count_function_nodes`()

    This function counts the amount function nodes that are present in the graph.

    Returns: | amount of function nodes counted in graph
    Return type: | int

  `create_dsm`(file_name, destination_folder=None, open_pdf=False, mpg=None, include_system_vars=True, summarize_vars=False, function_order=None, keep_tex_file=False, abbreviate_keywords=False, compile_pdf=True, colors_based_on='function_roles')

    Method to create a (X)DSM PDF file

    Parameters: | file_name (str) – name of the file to be saved destination_folder (str) – destination folder for the file to be saved open_pdf (bool) – option for opening the created file directly mpg (MdaoProcessGraph) – optional MPG graph to be saved with MDG as XDSM (if None a DSM is created) include_system_vars (bool) – option for including system variables (only applicable for DSMs) summarize_vars (bool) – option for summarizing label function_order (list) – optional function order for the diagonal of the graph (only applicable for DSMs) keep_tex_file (bool) – optional argument to keep the tex file of the PDF abbreviate_keywords (bool) – optional argument to keep make keywords shorter (input -> inp., output -> outp.) colors_based_on (str) – option to base the colors either on the problem role or the partitions

  `deepcopy`()

    Method to make a deep copy of a graph.

    Returns: | deepcopy of the graph
    Return type: | KadmosGraph

  `deepcopy_as`(graph_class)

    Method to make a deep copy of a graph and make it into another KADMOS graph class.

    Returns: | deepcopy of the graph
    Return type: | KadmosGraph

  `disconnect_problematic_variables_from`(function, disconnect_collided_targets=True, disconnect_shared_sources=True, ignore_list=[])

    Method to automatically disconnect certain problematic variables with respect to a given function.

    Parameters: | function (basestring) – function around which problematic variables are disconnected disconnect_collided_targets (bool) – setting to disconnect collided targets disconnect_shared_sources (bool) – setting to disconnect shared sources ignore_list (list) – setting to ignore certain nodes

    If given as setting (disconnect_collided_targets=True) then the collided targets will be disconnected from this function. Also, if given as setting (disconnect_shared_sources=True), shared sources are also disconnected.

  `find_all_nodes`(category='all', subcategory='all', attr_cond=None, attr_include=None, attr_exclude=None, xpath_include=None, xpath_exclude=None, print_in_log=False, print_attributes='all')

    Advanced search function to get nodes and their properties.

    Parameters: | category (str) – category of the node (you can specify multiple in a list), see note for allowed values. subcategory (str) – subcategory of the node (you can specify multiple in a list), see note for allowed values. attr_cond (list) – conditional on the node attribute value (e.g. [‘execution time’,’>’,200]) attr_include (list) – attributes to exclusively include in search attr_exclude (list) – attributes to exclude from search xpath_include (list) – xpaths to exclusively include in search xpath_exclude (list) – xpaths to exclude from search print_in_log (bool) – parameter to set printing in log on or off print_attributes (str or list) – attributes that should be printed in the log
    Returns: | list of all nodes that meet the search criteria
    Return type: | list

    Note

    The following categories are allowed:

    - all
    - variable
    - variable group
    - function
    - architecture element
    - RCE component

    Note

    The following subcategories are allowed:

    GROUPS:

    - all
    - all variables
    - all inputs
    - all outputs
    - all couplings
    - all circular variables
    - all PSG blocks
    - all iterative blocks
    - all design variables

    VARIABLES:

    - hole
    - supplied input
    - supplied shared input
    - output
    - collision
    - coupling
    - pure circular coupling
    - shared coupling
    - shared circular coupling
    - collided coupling
    - collided circular coupling
    - collided shared coupling
    - collided shared circular coupling

    VARIABLE GROUPS:

    - hole group
    - supplied input group
    - supplied shared input group
    - output group
    - coupling group
    - shared coupling group

    FUNCTIONS:

    - independent
    - source
    - sink
    - complete

    ARCHITECTURE ELEMENTS:

    Action blocks:

    - optimizer
    - MDA
    - optimizer function
    - MDA analysis
    - independent output function

    Parameters:

    - initial guess design variable
    - final design variable
    - final output variable
    - MDA coupling variable
    - initial guess MDA coupling variable
    - final MDA coupling variable
    - consistency constraint variable

    RCE COMPONENTS:

    - Input Provider
    - XML Merger
    - XML PyMerger
    - CPACS Tool
    - Converger
    - Optimizer
    - Consistency constraint function

    Example usage: Just get all nodes of a graph in a list:

        >>> all_nodes = self.find_all_nodes()

    Get all input nodes in a list and print them in the log as well:

        >>> all_nodes = self.find_all_nodes(category='all', subcategory='all inputs', print_in_log=True)

    Get all input nodes with a certain attribute value:

        >>> all_nodes = self.find_all_nodes(category='all', subcategory='all inputs',
        >>>                                 attr_cond=['execution time', '>', 5], print_in_log=True)

    Get all nodes with any of the listed attribute values:

        >>> all_nodes = self.find_all_nodes(category='all', subcategory='all',
        >>>                                 attr_include=[['problem_role', ['constraint', 'objective']],
        >>>                                               ['instance', 1]])

  `get_adjacency_matrix`(print_in_log=True)

    Function to determine the adjacency matrix of a graph.

    Parameters: | print_in_log (bool) – option for printing the results
    Returns: | different methods of storing the same adjacency matrix in one dictionary
    Return type: | dict

  `get_architecture_node_ids`(mdao_architecture, number_of_groups=None)

    Method to get the IDs of architecture nodes specific for a certain MDAO architecture.

    Parameters: | mdao_architecture (basestring) – specified architecture (CO, BLISS-2000, etc) number_of_groups (int, None) – number of subgroups in distributed architectures
    Returns: | node IDs
    Return type: | tuple

  `get_architecture_node_labels`(mdao_architecture, number_of_groups=None)

    Method to get the labels of architecture nodes specific for a certain MDAO architecture.

    Parameters: | mdao_architecture (basestring) – specified architecture (CO, BLISS-2000, etc) number_of_groups (int, None) – number of subgroups in distributed architectures
    Returns: | node labels
    Return type: | tuple

  `get_categorized_nodes`(print_in_log=False)

    Function that returns a dictionary with graph nodes grouped according to category and subcategory.

    Parameters: | print_in_log (bool) – option for printing the categories
    Returns: | dictionary with analysis results
    Return type: | dict

  `get_contracted_graph`(contraction_level)

    This function contracts the nodes of a graph to the provided contraction level.

    Parameters: | contraction_level (int) – from 0 (highest level) to X (lowest level existing in XML schema)
    Returns: | contracted_graph: graph with contracted nodes

    The contraction level refers to the xpath-level, which represents the position of the descendant with respect to its predecessors. The example below represents a level 3 node, with “cpacs” being at level zero.

    /cpacs/aircraft/wings/wing

    –cpacs

    —-aircraft

    ——–wings

    ————wing

    Note

    All nodes above the contraction level are removed from the graph and replaced by a “variable group” node, which groups the removed nodes in a node at contraction level. This allows for a “de-cluttering” of the graph, with the graph connections still being represented.

  `get_direct_coupling_nodes`(*args, **kwargs)

    This method returns the direct couplings between two nodes in a graph.

    Parameters: | args (str, list) – nodes to be checked for couplings; at least two must be provided kwargs (direction: str) – print_couplings: option for printing all couplings with coupling direction and node (optional) kwargs – direction: set only coupling in certain direction (optional)
    Returns: | couplings: list of tuples containing the coupled nodes and the coupling node
    Return type: | list

    This method is specifically written (and tested) with function nodes in mind. Direct coupling is defined as coupling with between two nodes through a third node.

    In this function, each combination between the provided arguments is tested for couplings (in pairs). First, the two nodes in each pair are checked for common neighbors. If they do, the edges of the common neighbors are iterated to determine whether the node-pair is connected to each other, or only the neighbor. The direction of the coupling is also checked.

    Example:

    - The connection: F1 => N1 => F2
    - Leads to: [(F1, F2, N1)]
  `get_first_node_instance`(node)

    Method to obtain the first instance of a node

    Parameters: | node (str) – node to find first instance of
    Returns: | node of first instance
    Return type: | str

  `get_function_graph`(keep_objective_variables=False)

    Method for replacing variable nodes by function connections.

    Param: | keep_objective_variables: if given the objective variables will remain in graph
    Type: | keep_objective_variables: bool
    Returns: | new graph without variable nodes

    Note

    This function removes all variable nodes from the graph and replaces the variable connections of each function with function connections, such that if N(i) is a variable node, and F(i) a function node:

    F(1) => N(1) => F(2) => N(2) => F(3)

    becomes: F(1) => F(2) => F(3)

  `get_function_metadata`(node)

    Function to get the node metadata in a list (used in the dynamic visualization package).

    Parameters: | node (basestring) – function node to collect the metadata for.
    Returns: | list with metadata
    Return type: | list

  `get_function_nodes`()

    This function returns a list of all function nodes in the graph.

  `get_graph_properties`(*args)

    This function retrieves the properties of a graph.

    Param: | args: specific properties to be retrieved (optional)
    Returns: | dictionary containing the properties of the graph
    Return type: | dict

    If no argument is given, the standard list of properties GRAPH_PROPERTIES is analyzed and their values are returned in a dict. If arguments are given, only this list will be used as standard list of properties.

  `get_node_attributes`(node, attr_list, print_in_log=False)

    Function to get and print certain attributes of a node from the graph.

    Parameters: | node (str) – node name attr_list (list) – list with attributes to be pulled print_in_log (bool) – option for printing to log
    Returns: | dictionary with node attributes
    Return type: | dict

  `get_node_subcategory`(node)

    Method to analyse a node and to update the subcategory attribute of the node.

    Parameters: | node (basestring) – node in the graph
    Returns: | subcategory of the node
    Return type: | basestring

    The following table illustrates how the subcategory is determined based on the category, indegree and outdegree:

    NODE CATEGORY | SUBCATEGORY | INDEGREE | OUTDEGREE
    --- | --- | --- | ---
    variable | hole | 0 | 0
    supplied input | 0 | 1
    supplied shared input | 0 | >1
    output | 1 | 0
    collision | >1 | 0
    coupling or pure circular coupling | 1 | 1
    shared coupling or shared circular coupling | 1 | >1
    collided coupling or collided circular coupling | >1 | 1
    collided shared coupling or collided shared circular coupling | >1 | >1
    function | independent | 0 | 0
    source | 0 | >0
    sink | >0 | 0
    complete | >0 | >0

  `get_nodes_based_on_strings`(*args, **kwargs)

    This function enables the user to search graph nodes for specific strings.

    Parameters: | args (str) – strings that graph nodes being searched for kwargs (include_all: bool) – include_all: If include_all is set to True, all matching nodes are added to returned list
    Returns: | matching nodes that user selected (all if include_all is True)

    Each provided string will be searched for, and if multiple node are found for each string, the user will be able to select the ones desired. The other matched nodes are disregarded.

  `get_nodes_indegree`()

    Function to get the indegree of all the graph nodes and store them in a dictionary.

    Returns: | dictionary with node name key and indegree integer value.
    Return type: | dict

  `get_nodes_outdegree`()

    Function to get the outdegree of all the graph nodes and store them in a dictionary.

    Returns: | dictionary with node name key and outdegree integer value.
    Return type: | dict

  `get_nodes_subcategory`()

    Method to analyse all nodes and to update the subcategory attributes of the nodes.

  `get_number_of_couplings`(node)

    This function returns the number of couplings of a node in the graph.

    Parameters: | node – input node
    Returns: | number of couplings for the input node
    Return type: | int

  `get_same_graph_class`(graph, copy_type='deep')

    Method to reinstantiate a given graph according to the same graph class as the self.

    Parameters: | graph (DiGraph) – graph object to be reinstantiated copy_type (basestring) – setting to have a deep or shallow copy of the graph
    Returns: | reinstantiated graph
    Return type: | KadmosGraph

  `get_source`(node)

    Function to determine the single source of a given node. Throws error if node has multiple sources.

    Parameters: | node (str) – node for which source should be found
    Returns: | source
    Return type: | str

  `get_sources`(node)

    Function to determine the sources of a given node.

    Parameters: | node (basestring) – node for which sources should be found
    Returns: | list with sources
    Return type: | list

  `get_subgraph_by_function_nodes`(*args, **kwargs)

    This function retrieves a subgraph from the original graph only containing the argument nodes.

    Parameters: | args (list, str) – arbitrary amount of graph nodes kwargs (copy_type: str) – copy_type: type of copy (clean or deep)
    Returns: | sub-graph only containing nodes provided as arguments, and their edges

    Note

    All arguments must be found in the graph.

  `get_system_inputs`(*args, **kwargs)

    This method checks whether there are system inputs in the graph using the function nodes provided.

    Parameters: | args – function nodes kwargs –
    Returns: | system input nodes dictionary
    Return type: | dict

    Note

    The function nodes should be provided in the args. If system inputs exist they are returned.

  `get_target`(node)

    Function to determine the single target of a given node. Throws error if node has multiple targets.

    Parameters: | node (str) – node for which target should be found
    Returns: | target
    Return type: | str

  `get_targets`(node)

    Function to determine the targets of a given node.

    Parameters: | node (basestring) – node for which targets should be found
    Returns: | list with targets
    Return type: | list

  `graph_has_nested_attributes`(*attrbs)

    Method to test if graph has nested attributes

    Parameters: | attrbs (str) – attributes to check for nesting in graph
    Returns: | presence of nested attribute
    Return type: | bool

  `has_nodes`(nodes)

    Function that checks whether all nodes given in a list are present in the graph.

    Parameters: | nodes (list) – list of nodes to be checked
    Returns: | boolean whether all nodes have been found
    Return type: | bool

  `inspect`()

    Method to print an overview of the graph.

    Returns: | printed overview of the graph
    Return type: | str

  `inspect_node`(node)

    Method to print a node with details.

    Parameters: | node (str) – node
    Returns: | printed node details
    Return type: | str

  `inspect_nodes`(list_of_nodes)

    Method to inspect/print a list of nodes with details.

    Parameters: | list_of_nodes (list) – node list
    Returns: | printed details of nodes
    Return type: | str

  `load_cmdows`(cmdows, check_list, ignore_modes=False, keep_running=False)

    Method to load the graph from a CMDOWS file

    Parameters: | cmdows (str) – CMDOWS file path check_list (list) – checks to be performed. See below. ignore_modes (bool) – for determining if modes are taken into account keep_running (bool) – for determining if errors should be raised
    Returns: | mpg
    Return type: | MdaoProcessGraph

    Note

    check_list options:

    - ‘consistent_root’: check if all in-/output files have the same root element
    - ‘invalid_leaf_elements’: check for leaf elements that still have child elements in other in-/output files
    - ‘schemas’: check if the in-/output files are consistent with the schema.

    To perform all of the checks without stopping if an error is found by the checks:

        >>> check_list = ['consistent_root', 'invalid_leaf_elements', 'schemas']
        >>> graph.load_cmdows(cmdows, check_list, keep_running=True)

  `make_all_variables_valid`()

    Method to analyze all variables in a graph and make any problematic variables valid.

    Returns: | graph with problematic variables removed.

    Problematic variable are holes and splittables. Splittable variables are split and holes will simply be removed.

  `merge_function_modes`(*args, **kwargs)

    Function to contract certain modes of the same function.

    Parameters: | args (str) – function (first arg) and then followed by modes to be contracted. kwargs (dict or str) – new_label to specify new node label manually (optional)
    Returns: | contracted graph
    Return type: | KadmosGraph

  `merge_function_nodes_based_on_modes`(merge_funcs=None)

    This class method merges all execution modes of the same function into a single node.

    Parameters: | merge_funcs (list, tuple) – List of tuple of functions to merge. If empty (default), all functions are merged.
    Returns: | merged graph

    Mainly used for illustration purposes since information on the execution modes gets lost. Functions must be present in graph.

  `merge_functions`(*args, **kwargs)

    Function to merge a collection of functions.

    Parameters: | args (node_ids) – functions to be merged kwargs (dict) – new_label to specify new node label manually (optional)
    Returns: | graph with merged function
    Return type: | KadmosGraph

  `merge_parallel_functions`(*args, **kwargs)

    Function to merge a list of functions

    Parameters: | args (node_ids) – functions to be merged kwargs (dict) – new_label to specify new node label manually (optional)
    Returns: | graph with merged functions
    Return type: | KadmosGraph

  `merge_sequential_functions`(*args, **kwargs)

    Function to merge a collection of functions.

    Parameters: | args (node_ids) – functions to be merged in the given sequence kwargs (str) – new_label to specify new node label manually (optional)
    Returns: | graph with merged functions
    Return type: | KadmosGraph

    Attention

    It is assumed that the merged functions are actually executed in the sequence in which they are given to this function.

  `node_is_function`(node)

    Function that checks whether a node is a function node or not.

    Parameters: | node (str) – node in graph
    Returns: | check result
    Return type: | bool

  `node_is_hole`(node)

    Function that checks whether a node is a hole (unconnected).

    Parameters: | node (str) – node in graph
    Returns: | check result
    Return type: | bool

  `node_is_objective_function`(node)

    This function checks whether the provided node is a objective function.

    Parameters: | node (str) – graph node to be tested
    Returns: | check result
    Return type: | bool

    This function checks whether the provided node:
      1. exists in graph
      2. has name-attribute “Objective”
      3. has an out-degree of 1
      4. has an outgoing node with an out-degree of zero

    Note

    Only if all checks are satisfied, is the node a valid objective function node.

  `node_is_output`(node)

    Function that checks whether a node is a system output.

    Parameters: | node (str) – node in graph
    Returns: | check result
    Return type: | bool

  `node_is_variable`(node)

    Function that checks whether a node is a variable node or not.

    Parameters: | node (str) – node in graph
    Returns: | check result
    Return type: | bool

  `plot_adjacency_matrix`(fig_num=1, fig_size=(7, 7), show_now=True)

    Draw the adjacency matrix in a plot window.

    Parameters: | fig_num – figure number fig_size – figure size show_now – Boolean whether to plot directly (pausing the execution until the plot is closed), or not.

  `plot_graph`(fig_num=1, color_setting='default', positioning='circular', save_as=None, show_now=True, title=None, edge_label=False)

    Function to plot a graph.

    Parameters: | fig_num (int) – figure number color_setting (str) – choose from ‘default’, ‘sinks’, ‘categories’, ‘partitions’ positioning (str) – choose from ‘circular’, ‘spring’ save_as (bool) – save plot as figure file show_now (bool) – Boolean whether to plot directly (pausing the execution until the plot is closed), or not. title (str) – title of the graph edge_label (str) – edge attribute that will be shown for each edge in graph
    Returns: | window with plot

    Hint

    if the plot window is not showing, you need to add matplotlib.pyplot.show() at the end of your code

  `print_graph`(use_pretty_print=False)

    Function to print the full graph.

    Parameters: | use_pretty_print (bool) – Boolean on whether to use pretty print for node and edge attributes

  `relabel_function_nodes`(mapping=None)

    Method to relabel all function nodes so that they meet the minimum CMDOWS convention

    Parameters: | mapping (None, bool) – application of mapping required, optional (default=None)
    Returns: | relabeled graph

    CMDOWS convention:

    - Minimum information: ID
    - Maximum information: ID[modeID][instanceID][version]

    Note

    modeID, instanceID and version are only provided if there is a function with the same ID that requires this specification to differentiate between the functions.

    Example:

    Design competences (full information):

    1. Aerodynamics[A][1][v1]
    2. Aerodynamics[A][2][v1]
    3. Aerodynamics[B][1][v1]
    4. Structures[A][1][v1]
    5. Structures[A}[1][v2]
    6. Propulsion[A][1][v2]

    Design competences relabeled:

    1. Aerodynamics[A][1]
    2. Aerodynamics[A][2]
    3. Aerodynamics[B][1]
    4. Structure[v1]
    5. Structure[v2]
    6. Propulsion
  `remove_function_nodes`(*args)

    Function that removes a function node

    Parameters: | args (str, list) – function node id(s)
    Returns: | graph with nodes removed
    Return type: | KadmosGraph

    Attention

    Also the input and output variables that only have links to this specific function node are deleted. A simple remove_node of a function node might lead to unconnected variables in the graph.

  `save`(file_name, file_type='kdms', graph_check_critical=True, destination_folder=None, mpg=None, description='', creator='', version='1.0', timestamp=datetime.datetime(2018, 12, 3, 13, 50, 18, 448724), keep_empty_elements=False, pretty_print=False, convention=True, integrity=False)

    Method to save the graph.

    Parameters: | file_name (str) – name of the file to be saved file_type (str) – file_type graph_check_critical (bool) – option for raising errors in case of an invalid graph destination_folder (str) – destination folder for the file to be saved mpg (MdaoProcessGraph) – optional MPG graph to be saved with MDG description (str) – description of the file (only applicable for the cmdows file type) creator (str) – name of the creator of the file (only applicable for the cmdows file type) version (str, float, int) – version of the file (only applicable for the cmdows file type) timestamp (datetime) – timestamp to be saved in the file (only applicable for the cmdows file type) keep_empty_elements (bool) – option for keeping empty XML elements (only applicable for the cmdows file type) pretty_print (bool) – option for pretty XML printing (only applicable for the cmdows file type) convention (bool) – option for appyling a UID convention (only applicable for the cmdows file type) integrity (bool) – option for doing an integrity file check (only applicable for the cmdows file type)

    Note

    Different output file types are implemented for saving graphs. They are listed below:

    - kdms: the most simple file type which makes use of pickling
    - cmdows: the most versatile file type especially suited for file exchange with other tools
    - graphml: another file type especially suited for file exchange with other tools based on graphs
  `select_objectives_from_graph`(*args)

    This functions lets the user select one or more objective functions from the graph.

    Parameters: | args (str) – objective functions to choose from
    Returns: | list of objective functions
    Return type: | list

    Note

    Only functions can be selected as objectives. If no arguments are provided, user is prompted to select an objective from all functions in graph.

  `split_variables`(*args, **kwargs)

    Method to split a problematic variable node into multiple separate valid nodes.

    Parameters: | args (basestring, list) – problematic node in the graph kwargs –
    Returns: | graph with split variables
    Return type: | KadmosGraph

    The following variables are considered problematic and will be handled by this function:

    - pure circular coupling
    - shared circular coupling
    - collided coupling
    - collision
    - collided circular coupling
    - collided shared coupling
    - collided shared circular coupling

    The following table shows an example situation for each of the different problematic variables:

    PROBLEMATIC VARIABLE | SITUATION | FUNCTION ORDER | RESOLVED AS
    --- | --- | --- | ---
    pure circular coupling | x1 <=> F1 | n.a. | x1/variableInstance1 => F1 => x1/variableInstance2
    shared circular coupling | F1 <=> x1 => F2, F3 | n.a. | x1/variableInstance1 => F1 => x1/variableInstance2 => F2, F3, etc.
    collided (shared) coupling | F1, F3 => x1 => F2, F4 | F1, F2, F3, F4 | F1 => x1/variableInstance1 => F2
    F3 => x1/variableInstance2 => F4
    collision | F1, F2 => x1 | F1, F2 | F1 => x1/variableInstance1
    F2 => x1/variableInstance2
    collided circular coupling | F1 <=> x1 <= F2, F3 | n.a. | x1/variableInstance1 => F1 => x1/variableInstance2
    F2 => x1/variableInstance3
    F3 => x1/variableInstance4
    collided shared circular coupling | F3, F5 <=> x1 <= F2 x1 => F1, F4, F6 | F1, F2, F3, F4, F5, F6 | x1/variableInstance1 => F2 => (..)
    x1/variableInstance2 => F1, F3 => (..)
    x1/variableInstance3 => F4, F5 => (..)
    x1/variableInstance4 => F6

### DataGraph

class `kadmos.graph.graph_data.` `DataGraph`(*args, **kwargs)
  `add_variable_default_values`(xml_file)

    Method to add the default value of the variables based on a reference XML file containing those values.

    Parameters: | xml_file (file) – path (absolute or local) to the XML file containing the default values
    Returns: | enriched graph with default values of the variables stored as attributes
    Return type: | self

  `function_nodes`

    Get list with all function nodes.

  `get_coupling_dictionary`()

    Function to get a coupling dictionary.

    Returns: | coupling dictionary
    Return type: | dict

    For each function node, the dictionary indicates from which function nodes it gets its input and the number of variables it gets.

    - F2 ==> x1, x2 ==> F1
    - F3 ==> x3 ==> F1

    Will give: {F1: {F2: 2, F3: 1}}

  `get_coupling_matrix`(function_order_method='manual', node_selection=None)

    Function to determine the role of the different functions in the FPG.

    Parameters: | function_order_method (basestring) – algorithm to be used for the order in which the functions are executed. node_selection (list) – selection of nodes for which the coupling matrix will be calculated only
    Returns: | graph with enriched function node attributes and function problem role dictionary
    Return type: | FundamentalProblemGraph

  `get_feedback_info`(function_order, coupling_dict=None, use_runtime_info=False)

    Function to determine the number of feedback loops and a runtime estimation for a given function order

    Parameters: | function_order (list) – function order of the nodes coupling_dict (dict) – coupling dictionary indicating the input/output relations between the nodes use_runtime_info (bool) – option to take the runtime of the functions into account, else the default is set to 1

    :return number of feedback loops :rtype int

  `get_highest_instance`(node)

    Method to get the highest instance of a node.

    Parameters: | node (str) – node
    Returns: | highest instance of the node
    Return type: | int

  `get_possible_function_order`(method, multi_start=None, check_graph=False, coupling_dict=None, node_selection=None, rcb=1.0, use_runtime_info=False)

    Method to find a possible function order, in the order: pre-coupling, coupled, post-coupling functions. If partitions have already been set, the partitions will be taken into account and the function order in each partition will be determined as well.

    Parameters: | method (str) – algorithm which will be used to minimize the feedback loops multi_start (int) – start the algorithm from multiple starting points check_graph (bool) – check whether graph has problematic variables coupling_dict (dict) – coupling dictionary of the graph node_selection (list) – option to get the order of only a selection of nodes instead of the entire graph rcb (float) – runtime-coupling balance, relative importance between feedback and runtime while optimizing function order. 1: min feedback, 0: min runtime use_runtime_info (bool) – option to use the runtime of the disciplines while determining the function order

    :return Possible function order :rtype list

  `get_runtime_sequence`(sequence, use_runtime_info=False, coupling_dict=None, get_time_line=False)

    Function to get the runtime of a sequence of nodes. Each node starts running as soon as all its required input data is available.

    Parameters: | sequence (list) – sequence of nodes use_runtime_info (bool) – option to use the runtime of the nodes, if False the runtime for each node is set to 1 coupling_dict (dict) – coupling dictionary of the graph get_time_line – option to return a time line which indicates at each time step which nodes are waiting

    for input, which nodes are running and which nodes are finished

  `mark_as_constraint`(node, operator, reference_value, remove_unused_outputs=False)

    Method to mark a node as a constraint.

    Parameters: | node (str) – node to be marked (on the left side of the operator operator (str or string list) – constraint operator or list of constraint operators reference_value (numbers.Number or list) – value on the right side of the operator or list of values corresponding to the list of operators remove_unused_outputs (bool) – option to remove unused outputs
    Returns: | graph with enriched constraint node

  `mark_as_constraints`(nodes, operators, reference_values, remove_unused_outputs=False)

    Method to mark multiple nodes as constraints.

    Parameters: | nodes (list) – nodes to be marked. operators (str, list) – operators to be implemented (as list per node or as single operator for all) reference_values (float, list) – reference values to be used (as list of values per node or as single value for all) remove_unused_outputs (bool) – option to remove unused outputs
    Returns: | graph with enriched constraint nodes

    Operators: ‘==’, ‘>’, ‘<’, ‘>=’ and ‘<=’

  `mark_as_design_variable`(node, lower_bound=None, upper_bound=None, samples=None, nominal_value=0.0, ignore_outdegree=False)

    Method to mark a single node as a design variable and add the required metadata for its definition.

    Parameters: | node (str) – node lower_bound (float) – lower bound of design variable upper_bound (float) – upper bound of design variable samples (list) – samples of design variable nominal_value (float) – nominal value of design variable ignore_outdegree (bool) – option to ignore the outdegree required
    Returns: | graph with enriched design variable node

  `mark_as_design_variables`(nodes, lower_bounds=None, upper_bounds=None, samples=None, nominal_values=None)

    Method to mark a list of nodes as design variable and add metadata.

    Parameters: | nodes (list or str) – list of nodes present in the graph lower_bounds (list, numbers.Number) – list of lower bound values upper_bounds (list, numbers.Number) – list of upper bounds samples (list) – nested list of kadmos values nominal_values (list, numbers.Number) – list of nominal values
    Returns: | graph with enriched design variable nodes

  `mark_as_objective`(node, remove_unused_outputs=False)

    Method to mark a single node as objective.

    Parameters: | node (basestring) – variable node remove_unused_outputs (bool) – option to remove unused outputs
    Returns: | graph enriched with objective node

  `mark_as_qoi`(node)

    Function to mark a list of nodes as quantity of interest.

    Parameters: | nodes (list) – list of nodes present in the graph remove_unused_outputs (bool) – option to remove unused outputs

  `mark_as_qois`(nodes, remove_unused_outputs=False)

    Function to mark a list of nodes as quantity of interest.

    Parameters: | nodes (list) – list of nodes present in the graph remove_unused_outputs (bool) – option to remove unused outputs

  `minimize_feedback`(nodes, method, multi_start=None, get_evaluations=False, coupling_dict=None, rcb=1, use_runtime_info=False)

    Function to find the function order with minimum feedback or minimum runtime

    Parameters: | nodes (list) – nodes for which the feedback needs to be minimized method (str) – algorithm used to find optimal function order multi_start (int) – start the algorithm from multiple starting points get_evaluations (bool) – option to get the number of evaluations needed by the algorithm as output coupling_dict (dict) – coupling dictionary of the graph rcb (float) – runtime-coupling balance, relative importance between feedback and runtime while optimizing function order. 1: min feedback, 0: min runtime use_runtime_info (bool) – option to use the runtime of the disciplines while determining the function order

    :return function order :rtype list :return number of evaluations (optional) :rtype int

  `remove_problematic_functions`()

    Remove functions that are independent or sinks

  `remove_unused_nodes`()

    Iteratively remove output nodes that do not have a problem role and then remove functions that have become sinks or independent.

    Returns: | the nodes that were removed
    Return type: | list

  `remove_unused_outputs`()

    Function to remove output nodes from an FPG which do not have a problem role.

    Returns: | the nodes that were removed
    Return type: | list

  `sort_nodes_for_process`(nodes, coupling_dict=None)

    Method to sort function nodes such that the correct process order is obtained. In case this function is used before the MDG is created, the number of feedback loops and runtime may change.

    Parameters: | nodes (list) – function nodes to sort coupling_dict (dict) – coupling dictionary of the graph
    Returns: | nodes in sorted order
    Return type: | list

  `unmark_variable`(node)

    Function to unmark any marked variable.

    Parameters: | node (basestring) – variable node to be unmarked
    Returns: | graph with unmarked node

  `variable_nodes`

    Get list with all variable nodes.

### RepositoryConnectivityGraph

class `kadmos.graph.graph_data.` `RepositoryConnectivityGraph`(*args, **kwargs)
  `create_mathematical_problem`(n_disciplines, coupling_density=None, n_clusters=1, cluster_strength=1, **kwargs)

    Function to get a mathematical problem according to the variable complexity problem as described in: Zhang D., Song B., Wang P. and He Y. ‘Performance Evaluation of MDO Architectures within a Variable Complexity Problem’, Mathematical Problems in Engineering, 2017.

    Parameters: | n_disciplines (int) – Number of disciplines coupling_density (float) – percentage of couplings, 0 no couplings, 1 all possible couplings n_clusters (int) – Number of clusters within the mathematical problem cluster_strength – Indicates the strength of the clustering. 0 means that a completely random problem is

    generated with no bias towards clustering at all. 1 means a complete bias towards clustering, so all couplings are placed within the clusters. If more couplings are required then the amount available within the clusters, couplings outside the clusters are made as well. :type cluster_strength: float :return enriched rcg with the mathematical problem :return dictionary containing the properties of the mathematical problem

  `get_fpg_based_on_function_nodes`(*args, **kwargs)

    Function to get the Fundamental Problem Graph based on a list of (or a single) function.

    Parameters: | args (str) – node names of functions of interest kwargs (name: str) – name: name of the graph to be generated
    Returns: | Fundamental Problem Graph object
    Return type: | FundamentalProblemGraph

  `get_fpg_based_on_list_functions`(list_of_functions, name='FPG')

    Function to get a Fundamental Problem Graph based on a list of functions.

    Parameters: | list_of_functions (list) – list with strings that specify the desired functions name (str) – name of the graph to be generated
    Returns: | Fundamental Problem Graph object
    Return type: | FundamentalProblemGraph

  `get_fpg_based_on_sinks`(list_of_sinks, name='FPG')

    Function to get the a Fundamental Problem Graph based on a list of sinks/required output variables.

    Parameters: | list_of_sinks (list) – list with strings that specify the desired output name (str) – name of the graph to be generated
    Returns: | Fundamental Problem Graph object
    Return type: | FundamentalProblemGraph

  `get_fpg_by_function_nodes`(*args)

    This function creates a new (FPG)-graph based on the selected function nodes.

    Parameters: | args (list, str) – arbitrary amount of graph nodes
    Returns: | new fpg graph
    Return type: | FundamentalProblemGraph

  `get_function_paths_by_objective`(*args, **kwargs)

    This function takes an arbitrary amount of objective nodes as graph sinks and returns all path combinations of tools.

    Parameters: | args (list, str) – arbitrary amount of objective nodes kwargs (bool, str) – filter options to limit possible path combinations
    Returns: | all possible FPG path combinations for the provided objective nodes

    If no arguments are given, user is prompted to select objectives from the graph.

    Hint

    The tool combinations are found using the function itertools.product() and can lead to significant computation times for large graphs. If this is the case, the user is prompted whether to continue or not.

    A variety of filters can be applied to the search of possible tools combinations, some of which reduce the computation time.

    Note

    kwargs:

    - obj_vars_covered - ensures that all objective variables are used in tool configurations
    - ignore_funcs - ignores functions for the config
    - source - source node; if provided, must be in config
  `get_path_combinations`(*args, **kwargs)

    This function takes lists of subsets and generates all possible combinations between them.

    Parameters: | args (list) – lists of subsets that will be used to find configurations kwargs (int) – see optional arguments
    Returns: | set of all unique path combinations

    This is done by using the itertools.product() function. If the amount of expected evaluations exceeds a pre-set minimum, the user will be asked if to continue or not; because the process can take a long time and use up many resources.

    Note

    Optional arguments:

    - min_func: minimum amount of functions in each configuration
    - max_func: maximum amount of functions in each configuration
  `select_function_combination_from`(*args, **kwargs)

    This function takes all provided workflow configurations and lists them according to their characteristics.

    Parameters: | args (list) – workflow configurations kwargs (bool, str, int) – see optional arguments
    Returns: | sorted list of workflow configurations
    Return type: | list

    Note

    Optional arguments:

    - ‘print_combos’ - option to print the combinations in a table
    - ‘n_limit’ - amount of combinations that will be printed in the table
    - ‘sort_by’ - characteristic to sort workflow configurations by
    - ‘sort_by ascending’ - option to sort workflow configurations by ascension
    - ‘plot_combos’ - option to plot the combinations in a graph

    The user can choose the workflow configuration from the list.

    A warning is given to the user if the amount of total configurations exceeds n = 1e4. Print limit is set to [0-20] by default.

    Note

    sort_by must be one of [“couplings”, “system_inputs”, “edges”, “nodes”].

### FundamentalProblemGraph

class `kadmos.graph.graph_data.` `FundamentalProblemGraph`(*args, **kwargs)
  `add_function_problem_roles`()

    Method to determine the function problem roles of the functions in an FPG.

    Returns: |
    Return type: |

  `add_problem_formulation`(mdao_definition, function_order, doe_settings=None)

    Method to add the problem formulation.

    Parameters: | mdao_definition (str) – MDF-GS, MDF-J, IDF, CO, BLIS-2000 function_order (list) – order or functions to be included in graph doe_settings (dict) – doe settings of the graph
    Returns: | graph enriched with problem formulation
    Return type: | Fundamental ProblemGraph

  `change_settings_distributed_convergence`()

    Function to change the settings when the distributed convergence is set as architecture.

    Options: - Add or remove a local converger for each partition - Set the convergence method within each partition (Gauss-Seidel (default) or Jacobi) - Let partitions run in sequence instead of parallel

  `check_and_get_coupled_functions_groups`(coupled_functions_groups=None)

    Method to obtain the coupled functions and check them if provided

    Parameters: | coupling_functions_groups (list) – (optional) coupled function groups
    Returns: | coupled function groups
    Return type: | list

    Checks whether the function is a node of the graph with the problem role ‘coupled’

  `check_and_get_design_variables`(des_vars=None)

    Method to obtain the design variable nodes and check them if provided

    Parameters: | des_vars (list) – (optional) design variable nodes
    Returns: | design variable nodes
    Return type: | list

    Checks whether the function is a node of the graph with the problem role ‘design variable’

  `check_and_get_post_coupling_functions`(post_coupling_functions=None)

    Method to obtain the post-coupled functions and check them if provided

    Parameters: | post_coupling_functions (list) – (optional) post-coupled function nodes
    Returns: | post-coupled function nodes
    Return type: | list

    Checks whether the function is a node of the graph with the problem role ‘post-coupled’

  `check_and_get_pre_coupling_functions`(pre_coupling_functions=None)

    Method to obtain the pre-coupled functions and check them if provided

    Parameters: | pre_coupling_functions (list) – (optional) pre-coupled function nodes
    Returns: | pre-coupled function nodes
    Return type: | list

    Checks whether the function is a node of the graph with the problem role ‘pre-coupled’

  `create_mdg`(mg_function_ordering, name='MDG')

    Function to automatically create an MDG based on an FPG.

    Parameters: | mg_function_ordering (dict) – dictionary with MDAO graph function ordering name (basestring) – name for the MDG graph
    Returns: | baseline MDG (only added additional action blocks, no changed connections)
    Return type: | MdaoDataGraph

  `create_mpg`(mg_function_ordering, name='MPG')

    Function to automatically create a MPG based on a FPG.

    Parameters: | mg_function_ordering (dict) – dictionary with MDAO graph function ordering name (basestring) – name for the MPG graph
    Returns: | unconnected FPG (only action blocks and their diagonal position)
    Return type: | MdaoProcessGraph

  `determine_scope_constraint_functions`(cnstrnt_vars=None, coupled_functions_groups=None, post_coupling_functions=None, pre_coupling_functions=None)

    Method to determine the scope (global, local) of the constraint functions based on the constraint variables and to determine on which coupled function groups the constraint function depends.

    Parameters: | cnstrnt_vars (list) – (optional) constraint variables to be determined coupled_functions_groups (list) – (optional) list of lists with coupled functions groups post_coupling_functions (list) – (optional) list with post-coupling functions
    Returns: | global constraint variables and functions, local constraint variables and functions, groups indices per constraint function
    Return type: | tuple

  `determine_scope_design_variables`(des_vars=None, coupled_functions_groups=None, pre_coupling_functions=None, post_coupling_functions=None)

    Method to determine the scope (global, local) of the design variables and to determine to which coupled function groups the design variable belongs.

    Parameters: | des_vars (list) – list of design variables (if not given, it is taken from the graph) coupled_functions_groups (list) – list with list of coupled function groups pre_coupling_functions (list) – list with list of pre-coupled function groups
    Returns: | list of global design variables, list of local design variables, dictionary with dependencies
    Return type: | tuple

  `get_group_couplings`(coupled_functions_groups=None)

    Method to obtain group couplings and their indices.

    Parameters: | coupled_functions_groups (list) – (optional) list of coupled function groups
    Returns: | group couplings present
    Return type: | list
    Returns: | index of coupled groups
    Return type: | dict

  `get_mdg`(name='MDG')

    Create the MDAO data graph for a given FPG.

    Parameters: | name (basestring) – name of the new graph
    Returns: | MDAO data graph
    Return type: | MdaoDataGraph

  `get_mg_function_ordering`()

    Method to determine the function ordering for MDAO graphs (FPG and MDG) based on an FPG.

    Returns: | function ordering dictionary
    Return type: | dict

  `get_objective_node`()

    Method to get the single (or non-existent) objective node from a graph.

    Returns: | objective node or None if no objective node is present
    Return type: | str, None

  `get_partition_info`(partitions, coupling_dict=None, use_runtime_info=False, local_convergers=False)

    Function to get information about the partitions. The functions returns:

    - Total number of connections to converge, divided in:
        - Number of feedback connections in each partition
        - Total number of cut edges due to the partitioning
    - Estimation of the runtime for each partition

    Parameters: | partitions (list) – list which indicates which nodes are in which partition coupling_dict (dict) – coupling dictionary indicating the input/output relations between the nodes use_runtime_info – option to take the runtime information of the nodes into account when determining the

    partitions :type use_runtime_info: bool :param local_convergers: option to add local convergers to the partitions if feedback within the partition exist :param local_convergers: bool :return total_connections: total number of connections to converge :return partition_variables: number of feedback connections in each partition :return system_variables: total number of cut edges due to the partitioning :return run_time_partitions: runtime estimation for each partition

    ..note:: If a converger is present in a partition, the iterations are not taken into account in the runtime estimation

  `get_sub_level_functions`(local_objective_function, local_cnstrnt_funcs, coupled_functions_group, mg_function_ordering=None, add_system_functions_to_subsystems=True)

    Method to obtain subsystem level functions.

    Parameters: | local_objective_function (str) – local objective function local_cnstrnt_funcs (list) – local constraint function(s) coupled_functions_group (list) – coupled functions mg_function_ordering (dict) – (optional) MdaoGraph function ordering
    Returns: | subsystem level functions
    Return type: | dict

  `get_sys_post_couplings`(sys_level_post_coupled, coupled_functions_groups=None)

    Method to obtain the system-level post-couplings functions.

    Parameters: | sys_level_post_coupled (list) – nodes with attributed problem role ‘post-coupling’ coupled_functions_groups (list) – (optional) list of coupled function groups
    Returns: | system-level post-coupling functions
    Return type: | list
    Returns: | indices ot system-level post-coupling functions
    Return type: | dict

  `get_system_level_functions`(global_objective_function, global_cnstrnt_functions, mg_function_ordering=None, add_system_functions_to_subsystems=True)

    Method to obtain system level functions

    Parameters: | global_objective_function (str) – global objective function global_cnstrnt_functions (list) – global constraint function(s) mg_function_ordering (dict) – MdaoGraph function ordering
    Returns: | system level functions
    Return type: | dict

  `impose_mdao_architecture`()

    Method to directly get both the MDG and MPG of an FPG.

    Returns: | MdaoDataGraph and MdaoProcessGraph
    Return type: | tuple

  `partition_graph`(n_parts, node_selection=None, use_runtime_info=False, local_convergers=False, rcb_partitioning=0.0, rcb_order=1.0, coupling_dict=None, tpwgts=None)

    Partition a graph using the Metis algorithm (http://glaros.dtc.umn.edu/gkhome/metis/metis/overview).

    Parameters: | n_parts – number of partitions requested (algorithm might provide less if the number of partitions is

    close to the number of nodes) :type n_parts: int :param node_selection: option to give the nodes that need to be included in the partitions. If none are given, the nodes in the partitions are selected based on the mdao architecture :type node_selection: list :param use_runtime_info: option to take the runtime information of the nodes into account when determining the partitions :type use_runtime_info: bool :param local_convergers: option to add local convergers to the partitions if feedback within the partition exist :type local_convergers: bool :param rcb_partitioning: runtime-coupling balance for partitioning, relative importance between cut edges and runtime while making the partitions. 1: min cut edges, 0: min runtime :type rcb_partitioning: float :param rcb_order: runtime-coupling balance for sequencing, relative importance between feedback and runtime while determining the function order within the partitions. 1: min feedback, 0: min runtime :type rcb_order: float :param coupling_dict: coupling dictionary indicating the input/output relations between the nodes :type coupling_dict: dict :param tpwgts: list of target partition weights :type tpwgts: list

    Note

    partitioning can only be performed on undirected graphs. Therefore every graph input is translated into an undirected graph.

  `select_number_of_partitions`(partition_range='pareto', node_selection=None, use_runtime_info=False, local_convergers=False, rcb_partitioning=0.0, rcb_order=1.0, coupling_dict=None, plot_solutions=False)

    Function to evaluate the properties of different number of partitions and to select the best one.

    Parameters: | partition_range – range of number of partitions that need to be evaluated. If set to ‘pareto’, a pareto

    front will be calculated. :type partition_range: list or str :param node_selection: option to give the nodes that need to be included in the partitions. If none are given, the nodes in the partitions are selected based on the mdao architecture :type node_selection: list :param use_runtime_info: option to take the runtime information of the nodes into account when determining the partitions :type use_runtime_info: bool :param local_convergers: option to add local convergers to the partitions if feedback within the partition exist :type local_convergers: bool :param rcb_partitioning: runtime-coupling balance for partitioning, relative importance between cut edges and runtime while making the partitions. 1: min cut edges, 0: min runtime :type rcb_partitioning: float :param rcb_order: runtime-coupling balance for sequencing, relative importance between feedback and runtime while determining the function order within the partitions. 1: min feedback, 0: min runtime :type rcb_order: float :param coupling_dict: coupling dictionary indicating the input/output relations between the nodes :type coupling_dict: dict :param plot_solutions: option to plot the characteristics of different number of partitions :type plot_solutions: bool

### MdaoProcessGraph

class `kadmos.graph.graph_process.` `MdaoProcessGraph`(*args, **kwargs)
  `add_process`(sequence, start_step, mdg, end_in_iterative_node=None)

    Method to add a process to a list of functions.

    The sequence is assumed to be the order of the functions in the input list. The sequence is considered simple, since it is not analyzed for the possibility to run functions in parallel.

    Parameters: | sequence (list) – list of functions in the required sequence start_step (int) – process step number for the first element in the sequence mdg (MdaoDataGraph) – data graph to be used for execution dependencies end_in_iterative_node (basestring) – (optional) iterative node to which the last function should go

  `add_process_partitions`(previous_sequence, partitions, next_sequence, start_step, mdg, end_in_iterative_node=None)

    Function to add the process in the partitions

    Parameters: | previous_sequence (list) – previous list of functions in the required sequence partitions (dict) – process partitions to be added next_sequence (list) – next list of functions in the required sequence start_step (int) – process step number for the first element in the sequence mdg (MdaoDataGraph) – data graph to be used for execution dependencies end_in_iterative_node (basestring) – (optional) iterative node to which the last function should go
    Returns: | graph enriched with process partitioning
    Return type: | MdaoProcessGraph

  `connect_nested_iterators`(master, slave, direction='slave->master')

    Method to connect a slave iterator to a master iterator in a nested configuration.

    Parameters: | master (basestring) – upper iterator node in the nested configuration slave (basestring) – lower iterator node in the nested configuration
    Returns: | graph enriched with nested iterators
    Return type: | MdaoProcessGraph

    An example is if a converger inside an optimizer in MDF needs to be linked back.

  `get_lowest_psn`(cycle)

    Method to retrieve the lowest process step number (PSN) of a list of nodes in a cycle.

    Parameters: | cycle (list) – list with nodes on a cycle
    Returns: | the minimal PSN and the index of the first element having this PSN
    Return type: | tuple

  `get_node_text`(node)

    Method to determine the text of a function node (for use in a XDSM diagram).

    Parameters: | node (basestring) – node
    Returns: | node text for in the XDSM function box
    Return type: | basestring

  `get_ordered_cycles`()

    Method to get the cycles of a process graph ordered according to process step number.

    Returns: | list with the cycles of a graph ordered based on PSN
    Return type: | list

  `get_process_hierarchy`()

    Method to assess the hierarchy of the process based on the process lines in a ProcessGraph.

    Returns: | nested list with process hierarchy, e.g. [COOR, A, [OPT, [CONV, D1, D2], F1, G1, G2]]
    Return type: | list

  `get_process_list`(use_d3js_node_ids=False)

    Method to get the xdsm workflow process list (for use in dynamic visualizations).

    Parameters: | use_d3js_node_ids (bool) – setting whether node names should be changed into node ids according to D3js notation.
    Returns: | process list
    Return type: | list

  `get_process_list_iteratively`(cycle_node, cycles)

    Method to obtain the process list of a collection of cycles given an iterative cycle_node. The process is iterative, since for every subcycle found the method is called again.

    Parameters: | cycle_node (str) – the node that is starting and closing the cycle (e.g. coordinator, optimizer, etc.) cycles (list) – collection of cycles found in the graph
    Returns: | the process list
    Return type: | list

    Note

    Example of a process list: [COOR, A, [OPT, [CONV, D1, D2], F1, G1, G2]]

  `get_process_order`(only_executable_block=True)

    Method to receive a list with the right order of the process based on process step numbers.

  `inspect_process`()

    Method to print the MPG.

    Returns: | printed inspection

### MdaoMixin

class `kadmos.graph.mixin_mdao.` `MdaoMixin`
  `insert_node_on_diagonal`(node, diagonal_pos, attr_dict=None)

    Function to insert a node on the diagonal with functions.

    Parameters: | node (str) – node identifier diagonal_pos (int) – integer with diagonal position (>= 0) attr_dict (dict) – dictionary with node attributes
    Returns: | graph with inserted node on diagonal
    Return type: | MdaoMixin

  `remove_node_from_diagonal`(node)

    Function to remove a node from the diagonal with functions.

    Parameters: | node (str) – node identifier
    Returns: | graph with removed node from diagonal
    Return type: | MdaoMixin

### EquationMixin

class `kadmos.graph.mixin_equation.` `EquationMixin`
  `add_equation`(edge_or_node, equation, language='Python')

    Method to add an equation to an output edge.

    Parameters: | edge_or_node (list, str) – graph edge or node under consideration. equation (str) – equation to be added language (str) – equation language used for the equation
    Returns: | equation
    Return type: | str

  `add_equation_label`(edge, labeling_method='node_label', language='Python')

    Method to add an equation label to a edge that can (safely) be used as reference in an equation.

    Parameters: | edge (str) – graph edge under consideration labeling_method (str) – select method for automatic label string determination (node_id or node_label) language (str) – equation language used for the equation label
    Returns: | label
    Return type: | str

  `add_equation_labels`(nodes, language='Python', labeling_method='node_id')

    Method to add equation labels automatically to all input edges connected to the specified list of nodes

    Parameters: | nodes (list) – list of nodes language (str) – equation language used for the equation label labeling_method (str) – select method for automatic label string determination (node_id or node_label)
    Returns: | labels
    Return type: | str

  `add_mathematical_function`(input_nodes, function_node, output_nodes, function_type='regular')

    Method to add mathematical function to graph

    Parameters: | input_nodes (str, list) – input nodes of the mathematical function function_node (str) – function node of the mathematical function output_nodes (str, list) – output nodes of the mathematical function function_type ('regular' or 'consistency') – type of function, optional (default=’regular’)
    Returns: | mathematical function
    Return type: | str

### VistomsMixin

class `kadmos.graph.mixin_vistoms.` `VistomsMixin`
  `vistoms_add`(vistoms_dir, mpg=None, function_order=None, reference_file=None, compress=False, remove_after_compress=True, graph_id=None, replacement_id=None, xml_file=None, file_refs_repl=None)

    Function to add a graph to a existing VISTOMS instance.

    Parameters: | vistoms_dir (str) – directory of the VISTOMS directory to be used for addition mpg (MdaoProcessGraph) – optional MPG graph to be saved with MDG as XDSM (if None a DSM is created) function_order (list) – optional function order for the diagonal of the graph (only applicable for DSMs) reference_file (str) – file from which reference values are extracted (either full path or file in same folder) compress (bool) – setting whether to compress the final VISTOMS instance folder to a zip file remove_after_compress (bool) – setting whether to remove the original folder after compression graph_id (basestring) – indentifier of the new graph replacement_id (basestring) – indentifier of the graph to be replaced xml_file (dict) – Name of the CMDOWS xml-file file_refs_repl – Replacement of existing file references in the original HTML
    Returns: | enriched vistoms instance
    Return type: | VistomsMixin

    Hint

    In one VISTOMS instance different graphs can be shown. For example it is possible to include different architectures for the same problem in one VISTOMS instance.

  `vistoms_add_json`(mpg=None, function_order=None, graph_id=None)

    Function to add a graph to a existing VISTOMS instance.

    In one VISTOMS instance different graphs can be shown. For example it is possible to include different architectures for the same problem in one VISTOMS instance.

    Parameters: | mpg (MdaoProcessGraph) – optional MPG graph to be saved with MDG as XDSM (if None a DSM is created) function_order (list) – optional function order for the diagonal of the graph (only applicable for DSMs)

  `vistoms_create`(vistoms_dir, vistoms_version=None, mpg=None, function_order=None, reference_file=None, compress=False, remove_after_compress=True, graph_id=None, use_png_figs=False, file_refs=None, xml_file=None)

    Function to create a new VISTOMS instance from a graph.

    Parameters: | vistoms_dir (str) – directory of the VISTOMS directory to be created vistoms_version – version of the VISTOMS instance to be used (as stored in the package itself) vistoms_version – str mpg (MdaoProcessGraph) – optional MPG graph to be saved with MDG as XDSM (if None a DSM is created) function_order (list) – optional function order for the diagonal of the graph (only applicable for DSMs) reference_file (str) – file from which reference values are extracted (either full path or file in same folder) compress (bool) – setting whether to compress the final VISTOMS instance folder to a zip file remove_after_compress (bool) – setting whether to remove the original folder after compression graph_id (basestring) – identifier of the new graph use_png_figs (bool) – setting whether to use the PNG figures instead of the SVG figures for local execution file_refs (dict) – setting to provide file references manually (to use VISTOMS on a server) xml_file (file) – Name of the CMDOWS xml file
    Returns: | vistoms instance
    Return type: | VistomsMixin

  `vistoms_start`(file_dir=None, mpg=None)

    Function to open an interactive VISTOMS based on the data graph and (optionally) the MPG. If file_dir is not provided then the files are stored in a temp directory.

    Parameters: | file_dir (path) – folder name or path where the graphs used in the interactive VISTOMS will be stored. mpg (MdaoProcessGraph) – MDAO process graph to be used in combination with the data graph.
    Returns: | interactive VISTOMS
    Return type: | file

## CMDOWS

Below the CMDOWS file operations library is listed.

class `kadmos.cmdows.cmdows.` `CMDOWS`(file_path=None, element=None)

  Class for with various methods for checking and manipulating CMDOWS files

  `add_actor`(contact_uid, role)

    Method to add a role element to the organization branch.

    Parameters: | contact_uid (basestring) – uID of the contact role (str) – contact role
    Returns: | enriched organizational branch
    Return type: | XMLSchema

    Note

    Role options are:

    - ‘architect’
    - ‘integrator’
    - ‘collaborative_engineer’
    - ‘tool_specialist’
    - ‘customer’
  `add_contact`(name, email, uid, company=None, department=None, function=None, address=None, telephone=None, country=None, roles=None)

    Method to add a contact element to the organization branch.

    Parameters: | name (str) – contact name email (str) – contact email uid (basestring) – contact uID company (str) – (optional) contact company department (str) – (optional) company department function (str) – (optional) contact function address (str) – (optional) contact address telephone (str) – (optional) contact telephone number country (str) – (optional) contact country roles (list, str) – contact roles in project
    Returns: | XML with contact
    Return type: | XMLSchema

    Note

    Role options are:

    - ‘architect’
    - ‘integrator’
    - ‘collaborative_engineer’
    - ‘tool_specialist’
    - ‘customer’
  `add_dc`(uid, id, mode_id, instance_id, version, label)

    Method to add a designCompetence element to the designCompetences branch.

    Parameters: | uid (basestring) – designCompetence uID id (str) – designCompetence ID mode_id (str) – designCompetence mode instance_id (int) – designCompetence instance version (str) – designCompetence instance label (str) – designCompetence label
    Returns: | XML with designCompetence
    Return type: | XMLSchema

  `add_dc_execution_details`(dc_uid, operating_system=None, integration_platform=None, command=None, description=None, software_requirements=None, hardware_requirements=None)

    Method to add a local execution info element to a dc branch.

  `add_dc_general_info`(dc_uid, description, status=None, creation_date=None, owner_uid=None, creator_uid=None, operator_uid=None, model_definition=None)

    Method to add a general info element to a DC branch.

    Parameters: | dc_uid (basestring) – designCompetence uID description (str) – designCompetence description status (str) – (optional) designCompetence status creation_date (datetime) – (optional) designCompetence creation date owner_uid (basestring) – (optional) designCompetence owner uID creator_uid (basestring) – (optional) designCompetence creator uID operator_uid (basestring) – (optional) designCompetence operator uID model_definition (str) – (optional) designCompetence model definition
    Returns: | XML with general info
    Return type: | XMLSchema

  `add_dc_inputs_element`(dc_uid, inputs_element)

    Method to add a input element to a DC element.

    Parameters: | dc_uid (basestring) – designCompetence uID inputs_element (str) – input element to be added
    Returns: | XML with input element
    Return type: | XMLSchema

  `add_dc_licensing`(dc_uid, license_type=None, license_specification=None, license_info=None)

    Method to add a licensing element to the generalInfo element of a DC branch.

    Parameters: | dc_uid (basestring) – designCompetence uID license_type (basestring) – type of license (open-source, commercial, etc) license_specification (basestring) – precise license specification (e.g. Apache License 2.0) license_info (basestring) – additional info or full license description
    Returns: | XML with license info
    Return type: | ExtendedElement

  `add_dc_outputs_element`(dc_uid, outputs_element)

    Method to add a output element to a DC element.

    Parameters: | dc_uid (basestring) – designCompetence uID outputs_element (str) – output element to be added
    Returns: | XML with output element
    Return type: | XMLSchema

  `add_dc_performance_info`(dc_uid, precision=None, fidelity_level=None, run_time=None, verification=None)

    Method to add a performance info element to a DC branch.

    Parameters: | dc_uid (basestring) – designCompetence uID precision (float) – (optional) designCompetence precision fidelity_level (int) – (optional) designCompetence fidelity level run_time (float) – (optional) designCompetence run time verification (dict) – designCompetence verification method
    Returns: | XML with performance info
    Return type: | XMLSchema

    Note

    the verification dict should contain the following keys:

    - ‘method’ (str)
    - ‘verifier’ (uid)
    - ‘result’ (str)
    - ‘date’ (datetime)
    - ‘version’ (str)
  `add_dc_remote_component_info`(dc_uid, single_or_multi_execution, job_name, remote_engineer, notification_message, data_exchange_dict=None)

    Method to add a remote execution info element to a dc branch.

  `add_dc_sources`(dc_uid, repository_link=None, download_link=None, references=None)

    Method to add a sources element to the generalInfo element of a DC branch.

    Parameters: | dc_uid (basestring) – designCompetence uID repository_link (basestring) – weblink to repository containing the design competence download_link (basestring) – weblink for downloading the design competence references (list) – list of references about the design competence (papers, websites, etc.)
    Returns: | XML with license info
    Return type: | ExtendedElement

  `add_dc_verification`(dc_uid, method, verifier, result, date, version)

    Method to add a verification to a DC branch.

    Parameters: | dc_uid (basestring) – designCompetence uID method (str) – verification method verifier (basestring) – verifier uID result (str) – verification result date (datetime) – verification date version – designCompetence uID that was verified
    Returns: | XML with verification added to DC
    Return type: | XMLSchema

  `add_header`(creator, description, timestamp=None, fileVersion='0.0', cmdowsVersion='0.8')

    Method to add a header to a CMDOWS file.

    Parameters: | creator (str) – name of creator description (str) – description of file content timestamp (str) – (optional) date and time of creation fileVersion (str) – version of the file cmdowsVersion (str) – version of the xsd schema
    Returns: | XML with header
    Return type: | XMLSchema

  `add_new_parameters_from_element`(parameters_element)

    Method to add the new parameters based on a parameters element.

    Parameters: | parameters_element (element) – new parameters
    Returns: | enriched parameters branch
    Return type: | XMLSchema

  `add_subelement`(element, subelement_xpath_tag)

    Method to add a subelement to an existing element.

    Parameters: | element (element) – element to be added to subelement_xpath_tag (xpath/tag) – subelement to be added.
    Returns: | enriched element branch
    Return type: | XMLSchema

  `add_valid_ranges`(elem_or_uid, minimum=None, maximum=None, list_range=None)

    Method to add the list ranges element to an existing element.

    Parameters: | elem_or_uid (str or ExtendedElement) – element or the UID of an element minimum (float) – minimum value for valid range maximum (float) – maximum value for valid range list_range (list) – list of optional values

  `append_element_to_uid_element`(uid, element_to_add, expected_tag_uid_el=None, expected_tag_new_el=None)

    Generic method to add a subelement to an element with a certain UID.

    Parameters: | uid (basestring) – uID of element to be added to element_to_add (str) – subelement to be added expected_tag_uid_el (str) – expected tag of element expected_tag_new_el (str) – expected tag of subelement
    Returns: | XML with subelement
    Return type: | XMLSchema

  `append_element_to_xpath_element`(xpath, element_tag, attrib=None)

    Method to append a new element at an XPath location.

    Parameters: | xpath (basestring) – unique XPath location where the element should be appended element_tag (basestring) – name of the new element to be appended
    Returns: | appended element
    Return type: | ExtendedElement

  static `assert_element_tag`(el, expected_tag)

    Method to assert that the tag of an element is as expected.

    Parameters: | el – element expected_tag (str) – expected tag
    Rtype el: | str

  `check`()

    Method to execute all checks and remove unused contacts

    Returns: | overall check result
    Return type: | bool

  `check_references`()

    Method to check if references are actually pointing to a uID in a CMDOWS file

    Returns: | result of reference check
    Return type: | bool

  `check_schema`()

    Method to check if a CMDOWS file adheres to its schema

    Returns: | result of schema check
    Return type: | bool

  `check_uids`()

    Method to check if all uIDs are actually unique in a CMDOWS file

    Returns: | result of unique uID check
    Return type: | bool

  `ensure_abs_xpath`(xpath)

    Method to ensure that the elements given by an absolute XPath exist.

    Parameters: | xpath (basestring) – XPath to be checked
    Returns: | checked XPath
    Return type: | basestring

  `get_design_competences_uids`()

    Method to get a list of all the design competences UIDs present in the file.

    Returns: | design competence uIDs
    Return type: | list

  `get_element_of_uid`(uid, expected_tag=None)

    Method to get the element based on a UID value.

    Parameters: | uid (basestring) – uID of element expected_tag (str) – (optional) expected tag
    Returns: | element
    Return type: | str

  `get_executable_blocks_uids`()

    Method to get a list of all the executable block UIDs present in the file.

    Returns: | executable blocks uIDs
    Return type: | list

  `get_inputs_uids`(exblock_uid)

    Method to collect the inputs of a CMDOWS file executableBlock entry

    Parameters: | exblock_uid (basestring) – uid of the executableBlock entry
    Returns: | path to input
    Return type: | xpath

  `get_mathematical_functions_uids`()

    Method to get a list of all the mathematical functions UIDs present in the file.

    Returns: | mathematical functions uIDs
    Return type: | list

  `get_outputs_uids`(exblock_uid)

    Method to collect the outputs of a CMDOWS file executableBlock entry

    Parameters: | exblock_uid (basestring) – executableBlock entry
    Returns: | path to output
    Return type: | xpath

  `get_parameters_uids`()

    Method to get a list of all the parameter UIDs present in the file.

    Returns: | parameter uIDs
    Return type: | list

  `get_used_parameter_uids`()

    Method to get a list of all the parameter UIDs used in the file.

    Returns: | parameter uIDs
    Return type: | list

  `get_xpath_of_uid`(uid, expected_tag=None)

    Method to get the xpath based on a UID value.

    Parameters: | uid (basestring) – uID of xpath expected_tag (str) – (optional) expected_tag
    Returns: | xpath of element
    Return type: | xpath

  `refresh_element_xpath`(xpath)

    Method to refresh an element based on an XPath. This means the element is removed if it exist and a new element is created and returned.

    Parameters: | xpath (basestring) – XPath of the element to be refreshed.
    Returns: | refreshed element
    Return type: | ExtendedElement

  `remove_actor`(role, uid)

    Method to remove a role from the organization for a certain contact.

    Parameters: | role (str) – role to be removed from contact uid (basestring) – uID of contact
    Returns: | Organization branch without contact role
    Return type: | XMLSchema

    Note

    Role options are:

    - ‘architect’
    - ‘integrator’
    - ‘collaborativeEngineer’
    - ‘toolSpecialist’
    - ‘customer’
  `remove_children_of_uid`(uid, children_to_remove='__all__', children_to_keep='__none__')

    Method to remove the children of a CMDOWS file element based on a uID.

    Parameters: | uid (basestring) – uID of the element to remove the children of children_to_remove (element) – (optional) list of children to be removed (default: remove all) children_to_keep (element) – (optional) list of children to be kept (default: keep none)
    Returns: | element with (certain) children removed
    Return type: | XMLSchema

    Attention

    make sure the child elements contained in the two lists do not overlap.

  `remove_children_of_xpath`(xpath, children_to_remove='__all__', children_to_keep='__none__')

    Method to remove the children of a CMDOWS file element based on an XPath.

    Parameters: | xpath (basestring) – XPath of the element to remove the children of children_to_remove (element) – (optional) list of children to be removed (default: remove all) children_to_keep (element) – (optional) list of children to be kept (default: keep none)
    Returns: | element with (certain) children removed
    Return type: | XMLSchema

    Attention

    make sure the child elements contained in the two lists do not overlap.

  `remove_contact`(contact_uid)

    Method to remove a contact based on its uID.

    Parameters: | contact_uid (basestring) – uID of the contact to be removed
    Returns: | Schema without contact
    Return type: | XMLSchema

  `remove_data_graph_element`()

    Method to remove a dataGraph element from a CMDOWS file.

    Returns: | Schema without dataGraph
    Return type: | XMLSchema

  `remove_element_based_on_uid`(uid, expected_tag=None)

    Method to remove an element based on its uID.

    Parameters: | uid (basestring) – uID of element to be removed expected_tag (str) – (optional) the expected tag of the element
    Returns: | Schema without element
    Return type: | XMLSchema

  `remove_element_based_on_xpath`(xpath, expected_amount=None, expected_text=None, higher_level_removal=None)

    Method to remove an element based on its XPath.

    Parameters: | xpath (basestring) – XPath of element to be removed expected_amount (int) – (optional) the expected amount of elements with this path expected_text (str) – (optional) the expected text of the element higher_level_removal (int) – (optional) the amount of higher levels to be removed
    Returns: | Schema without element
    Return type: | XMLSchema

  `remove_in_and_outputs`(exblock_uid)

    Method to remove the in- and outputs of a CMDOWS file executableBlock entry.

    Parameters: | exblock_uid (basestring) – executableBlock to remove the in- and outputs from
    Returns: | executableBlock without in- and outputs
    Return type: | XMLSchema

  `remove_inputs`(exblock_uid)

    Method to remove the inputs of a CMDOWS file executableBlock entry.

    Parameters: | exblock_uid (basestring) – executableBlock to remove the inputs from
    Returns: | executableBlock without inputs
    Return type: | XMLSchema

  `remove_outputs`(exblock_uid)

    Method to remove the outputs of a CMDOWS file executableBlock entry.

    Parameters: | exblock_uid (basestring) – executableBlock to remove the outputs from
    Returns: | executableBlock without outputs
    Return type: | XMLSchema

  `remove_parameter`(param_uid)

    Method to remove a parameter based on its uID.

    Parameters: | param_uid (basestring) – uID of parameter to be removed
    Returns: | Schema without parameter
    Return type: | XMLSchema

  `remove_parameters`(params_uids)

    Method to remove a list of parameters based on their uID.

    Parameters: | params_uid – uIDs of parameters to be removed
    Returns: | Schema without parameters listed
    Return type: | XMLSchema

  `remove_parameters_element`()

    Method to remove a parameters element from a CMDOWS file.

    Returns: | Schema without parameters
    Return type: | XMLSchema

  `remove_process_graph_element`()

    Method to remove a processGraph element from a CMDOWS file.

    Returns: | Schema without processGraph
    Return type: | XMLSchema

  `remove_unused_contacts`()

    Method to check if there are uID in CMDOWS file which are not referred to and remove them

    Returns: | XML without unused uID’s
    Return type: | XMLSchema

  `remove_workflow_element`()

    Method to remove a workflow element from a CMDOWS file.

    Returns: | Schema without workflow
    Return type: | XMLSchema

  `resolve_uids`()

    Method to rename duplicate uIDs in a CMDOWS file.

    Returns: | renamed duplicate uIDs
    Return type: | XMLSchema

  `save`(file_path=None, pretty_print=False, method='xml', xml_declaration=True, encoding='UTF-8')

    Method to save a manipulated CMDOWS file.

    Parameters: | file_path (basestring) – file path of the CMDOWS pretty_print (bool) – (optional) method (str) – (optional) output method (see options below, default: “xml”) xml_declaration (bool) – (optional) addition of XML declaration to file encoding (str) – (optional) output encoding (see options below, default: “UTF-8”)

    Note

    Output method options:

    - “xml”
    - “html”
    - “text”
    - “c14n”

    Note

    Output encoding options:

    - “UTF-8”
    - “US-ASCII”
  `schema`()

    Method to retrieve a schema either belonging to the CMDOWS file

    Returns: | schema
    Return type: | XMLSchema

  `simplify`()

    Method to simplify everything

  `simplify_equations`()

    Method to replace duplicate equations elements by a single equations element and refs to this element

    Returns: | XML with simplified equation
    Return type: | XMLSchema

  `version`()

    Method to retrieve the version of the CMDOWS file

    Returns: | version
    Return type: | str

## Utilities

Below the utilities used by KADMOS are listed.

### General

`kadmos.utilities.general.` `assert_dict_keys`(dic, expected_keys, all_keys_required=False)

  Method to assert that a dictionary has the expected keys and (optionally) to check if is has all the keys.

  Parameters: | dic (dict) – dictionary to checked expected_keys (list) – keys expected in dictionary all_keys_required (bool) – (optional) to check if all keys are in the dictionary
  Returns: | check results

`kadmos.utilities.general.` `color_list`()

  A list of distinguisable colors.

  Returns: | list with HTML Hex colors

`kadmos.utilities.general.` `convert_bytes`(num)

  Function to convert bytes to KB, MB, GB, TB.

  Parameters: | num (int) – number of bytes
  Returns: | converted number
  Return type: | str

`kadmos.utilities.general.` `dict_to_ord_dict`(dic, key_order)

  Method to transform a Python dictionary into a Python ordered dictionary.

  Parameters: | dic (dict) – dictionary key_order (list) – order of the keys
  Returns: | ordered dictionary
  Return type: | OrderedDict

  Note

  the key_order list can have items that are not present in the given dictionary. All keys of the dictionary should be in the order though.

`kadmos.utilities.general.` `export_as_json`(data, filename, indent=None, sort_keys=True, cwd=None)

  Function to export a data object to a json file.

  Parameters: | data (dict or list) – object with the data to be exported filename (basestring) – name of the json file indent (int) – number of spaces for one indentation sort_keys (bool) – option for sorting keys cwd (None, str) – current working directory
  Returns: | json file
  Return type: | file

`kadmos.utilities.general.` `file_size`(file_path)

  Function to return the file size.

  Parameters: | file_path (str) – file path
  Returns: | file size
  Return type: | str

`kadmos.utilities.general.` `file_size_MB`(file_path)

  Function to return the file size in MB.

  Parameters: | file_path (str) – file path
  Returns: | file size in MB
  Return type: | float

`kadmos.utilities.general.` `filter_group_vars`(group_dict, current_group_idx, filter_setting)

  Method to get the variables of a local/external group.

  Parameters: | group_dict (dict) – local/external group current_group_idx (int) – index of the current group filter_setting (list, string) – filter on ‘local’ or ‘external’ groups
  Returns: | group variables
  Return type: | list

`kadmos.utilities.general.` `format_string_for_latex`(string, prefix='', suffix='')

  Function to format a string such that it can be used in LaTeX.

  Parameters: | string (str) – string to be formatted prefix (basestring) – prefix to be placed in front of the string suffix (basestring) – suffix to be appended to the string
  Returns: | formatted string
  Return type: | basestring

`kadmos.utilities.general.` `format_string_for_vistoms`(string, prefix='', suffix='')

  Function to format a string such that it can be used in VISTOMS.

  Parameters: | string (str) – string to be formatted prefix (basestring) – prefix to be placed in front of the string suffix (basestring) – suffix to be appended to the string
  Returns: | formatted string
  Return type: | basestring

`kadmos.utilities.general.` `format_string_for_vistoms_new`(string, prefix='', suffix='')

  Function to format a string such that it can be used in VISTOMS.

  Parameters: | string (str) – string to be formatted prefix (basestring) – prefix to be placed in front of the string suffix (basestring) – suffix to be appended to the string
  Returns: | formatted string
  Return type: | basestring

`kadmos.utilities.general.` `get_element_dict`(xpath, var_value=None, var_dim=None, include_reference_data=False)

  Function to create a D3.js-type dictionary for a nested tree based on an xpath.

  Parameters: | xpath (basestring) – xpath for the element var_value (float) – value of the element in a reference file var_dim (int) – dimension of the element in a reference file include_reference_data (bool) – setting on whether reference data should be include in the path
  Returns: | nested dictionary
  Return type: | dict

`kadmos.utilities.general.` `get_friendly_id`(uid_length)

  Create a recognisable ID string.

  Parameters: | uid_length (int) – length of the ID
  Returns: | new ID
  Return type: | str

`kadmos.utilities.general.` `get_group_vars`(sa, current_group_idx)

  Method to get the variables with respect to the subgroup.

  Parameters: | sa (dict) – system analysis dictionary current_group_idx (int) – index of the subgroup
  Returns: | multiple lists with variables
  Return type: | tuple

`kadmos.utilities.general.` `get_list_entries`(*args)

  Utility to return only certain values of a given list based on the indices.

  Parameters: | args (list and int) – list and indices
  Returns: | list with requested values at indices
  Return type: | list

`kadmos.utilities.general.` `get_mdao_setup`(mdao_setup)

  Simple function to specify the MDAO architecture and convergence type based on a single string.

  Parameters: | mdao_setup (str) – MDF-GS, MDF-J, IDF
  Returns: | mdo_architecture, mda_type, allow_unconverged_couplings
  Return type: | str

`kadmos.utilities.general.` `get_uid`(preference, uids)

  Simple function to determine a valid uid which is not part of the uids list

  Parameters: | preference (str) – preferred name for the uid uids (list) – list of existing uids
  Returns: | a valid uid which
  Return type: | str

`kadmos.utilities.general.` `get_unique_friendly_id`(used_ids, uid_length)

  Return an ID that is not in our list of already used IDs.

  Parameters: | used_ids (list) – already used IDs uid_length (int) – length of the ID
  Returns: | new unique ID
  Return type: | str

`kadmos.utilities.general.` `hex_to_rgb`(value)

  Function to translate a hex color string to an RGB color tuple.

  Parameters: | value (str) – HTML hex color
  Returns: | RGB colors
  Return type: | tuple

`kadmos.utilities.general.` `make_camel_case`(string, make_plural_option=False)

  Function to make a string camelCase.

  Parameters: | string (str) – non-camelcase string make_plural_option (bool) – pluralize camelcase string
  Returns: | camelcase string
  Return type: | str

`kadmos.utilities.general.` `make_plural`(string)

  Function to convert a string to its plural form.

  Parameters: | string (str) – initial string
  Returns: | plural string
  Return type: | str

`kadmos.utilities.general.` `make_singular`(string)

  Function to convert a string to its singular form.

  Parameters: | string (str) – initial string
  Returns: | singular string
  Return type: | str

`kadmos.utilities.general.` `open_file`(filename)

  Utility to open a file cross-platform.

  Parameters: | filename – Filename including extension and path, e.g. ‘sampledir/samplefile.pdf’
  Returns: | An opened file

`kadmos.utilities.general.` `remove_if_exists`(input_list, entries_to_remove)

  Utility to remove certain values from a list.

  Parameters: | input_list (list) – initial list entries_to_remove (list) – values to remove
  Returns: | list with removed entries
  Return type: | list

`kadmos.utilities.general.` `test_attr_cond`(attr_value, operator, test_value)

  Function to check a given conditional statement and return True or False.

  Parameters: | attr_value (str, float, int) – value of the actual attribute operator (str) – conditional operator to be used (‘<’,’<=’,’==’,’!=’,’>=’,’>’, ‘in’) test_value (str, float, int) – value to which the attribute value should be compared.
  Returns: | result of the conditional statement.
  Return type: | bool

`kadmos.utilities.general.` `transform_data_into_strings`(data, keys_to_be_removed=[])

  Utility function to transform certain data types in a dictionary into strings.

  Parameters: | data (dict) – dictionary with data keys_to_be_removed (list) – list of keys that have to be removed from the dict
  Returns: | adjusted dictionary
  Return type: | dict

`kadmos.utilities.general.` `transform_string_into_format`(data, keys_to_be_removed=[])

  Utility function to transform certain strings back into their original data format (NoneType, list, etc.).

  Parameters: | data (dict) – dictionary with data keys_to_be_removed (list) – list of keys that have to be removed from the dict
  Returns: | adjusted dictionary
  Return type: | dict

`kadmos.utilities.general.` `translate_dict_keys`(dictionary, translations)

  Utility to (recursively) translate all keys in a dictionary with a translation dictionary.

  Parameters: | dictionary (dict) – dictionary to be translated translations (dict) – dictionary used for the translation
  Returns: | translated dictionary
  Return type: | dict

`kadmos.utilities.general.` `translate_list`(l, dictionary)

  Utility to quickly translate all elements in a list with a dictionary.

  Parameters: | l (list) – list to be translated dictionary (dict) – dictionary used for the translation
  Returns: | translated list
  Return type: | list

`kadmos.utilities.general.` `unmake_camel_case`(string, separator='_')

  Function to make camelCase a string with separator (e.g. underscores).

  Parameters: | string (str) – camelCase string separator (str) – symbol/symbols used as separator
  Returns: | string with separator
  Return type: | str

`kadmos.utilities.general.` `zip_file`(file_to_zip, destination_archive=None, name_of_zipped_file=None)

  Method to zip a single file as an archive.

  Parameters: | file_to_zip (basestring) – path to the file to be zipped destination_archive (basestring) – path to the archive to be created name_of_zipped_file (basestring) – name of the file inside the archive
  Returns: | path to the ZIP-file
  Return type: | basestring

### XML

`kadmos.utilities.xml.` `Element`()

  makeelement(self, _tag, attrib=None, nsmap=None, **_extra)

  Creates a new element associated with this parser.

`kadmos.utilities.xml.` `get_element_details`(tree, xpath)

  Function to determine the value and dimension of an UXPath element in a reference file.

  Parameters: | tree – ElementTree object used for finding the XPath xpath – XPath
  Returns: | element value and dimension

`kadmos.utilities.xml.` `get_uid_search_xpath`(uid)

  Method to get the XPath expression for a UID which might contain quote characters.

  Parameters: | uid (str) – uID string
  Returns: | XPath expression
  Return type: | str

`kadmos.utilities.xml.` `merge`(a, b)

  Recursive function to merge a nested tree dictionary (D3.js convention) into a full tree dictionary.

  Parameters: | a (dict) – full dictionary in which a new element is merged b (dict) – element dictionary of the new element
  Returns: | merged dictionary
  Return type: | dict

`kadmos.utilities.xml.` `recursively_empty`(element)

  Utility function to check recursively if a ElementTree object is empty.

  Parameters: | element – Input ElementTree object
  Returns: | Result of the check

`kadmos.utilities.xml.` `recursively_stringify`(tree)

  Utility function to recursively stringify a ElementTree object (for file comparison).

  Parameters: | tree – Input ElementTree object
  Returns: | List of strings representing the ElementTree object

`kadmos.utilities.xml.` `recursively_unique_attribute`(element, attribute='uID')

  Utility function to check recursively if the values of an attribute of an ElementTree object are unique.

  Parameters: | element – Input ElementTree object attribute – Name of the attribute being checked for uniqueness
  Returns: | Result of the check

### Strings

`kadmos.utilities.strings.` `find_between`(s, first, last)

  Function to find a target string that is located between two particular strings.

  Parameters: | s (basestring) – string to search first (basestring) – the string in front of the target string last (basestring) – the string behind the target string
  Returns: | the target string
  Return type: | basestring

`kadmos.utilities.strings.` `find_until`(s, until)

  Function to find a target string that is located before a particular string.

  Parameters: | s (basestring) – string to search until (basestring) – the string signifying the end of the target string
  Returns: | target string
  Return type: | basestring

`kadmos.utilities.strings.` `get_correctly_extended_latex_label`(label, label_extension)

  Function to obtain a correctly extended latex label.

  Parameters: | label (str) – label to be extended label_extension (str) – extensions of the label
  Returns: | extended latex label
  Return type: | str

### Printing

`kadmos.utilities.printing.` `print_in_table`(print_container, **kwargs)

  This function prints a table using the provided data and the headers. The “tabulate” library is used.

  Parameters: | print_container (iterable) – container for iterables –> [[row1], [row2], …] kwargs (str, bool) – keyword arguments for printing

  Note

  Kwargs options:

  - ‘header’ (str)
  - ‘message’ (str)
  - ‘print_indeces’ (bool)

`kadmos.utilities.printing.` `print_indexed_list`(*args, **kwargs)

  This function prints an indexed column of the given arguments in the console. The provided message is printed above the indexed column. Can be used in combination with user_prompt_select_options().

  Parameters: | kwargs – message: Message printed above indexed column kwargs – index_bracket: Type of bracket used for indeces in list (“round” or “squared”), default is round args – Arguments listed in column by index
  Returns: | printed indexed column of arguments in console

  Example use:

      >>> print_indexed_list(message="These are the tools: ", index_bracket="round", *list_of_tools)