Python Interface

class gboml.GbomlGraph(timehorizon=1)

GbomlGraph makes it possible to define and solve a GBOML model.

The GbomlGraph class enables the construction of GBOML models by importing nodes and hyperedges from a GBOML file. It also possesses a set of functions for updating the imported nodes and hyperedges (e.g., re-defining parameters or the type of variables). Nodes and hyperedges can be added to a GbomlGraph instance, from which the model can be solved and generated.

Parameters

timehorizon (int) – length of optimization horizon considered

Variables
  • list_nodes – nodes included in model

  • list_hyperedges – hyperedges included in model

  • timehorizon – optimization horizon object

  • node_hyperedge_dict – dictionary of all nodes and hyperedges

  • program – Program class of generated model (= None if model not generated)

  • matrix_a – constraint matrix A in sparse COO format (= None if model not generated)

  • matrix_b – upper bound on each row in constraint matrix (i.e., right-hand side coefficients, = None if model not generated)

  • vector_c – vector of objective coefficients (= None if model not generated)

  • indep_term_c – objective offset (i.e., constant term in the objective, = None if model not generated)

add_global_parameter(identifier, value)

Add one global parameter objects to the graph

Parameters
  • identifier (str) – parameter name

  • value (int|float|str) – value associated to the parameter (if string it expects a filename to read from)

Returns:

add_global_parameters(global_parameters)

Add global parameters objects to the graph

Parameters

global_parameters (list) – list of Parameter object or tuples of <parameter_name, values> where values can be an int/float/list <int/float> or a string to import from.

Returns:

add_global_parameters_objects(global_parameters)

Add global parameters objects from list of parameters objects Warning this function will be removed in future release ! Use add_global_parameters instead

Parameters

global_parameters (list) – list of global parameters

Returns:

add_hyperedges_in_model(*hyperedges)

bound method adding hyperedges to a GbomlGraph instance

Parameters

hyperedges (list <Hyperedge>) – list of hyperedge objects to be added

add_nodes_in_model(*nodes)

bound method adding nodes to a GbomlGraph instance

Parameters

nodes (list <Nodes>) – list of node objects to be added

static add_sub_hyperedge(hyperedge_to_add, in_node)

static method adding a sub-hyperedge to a given node

Parameters
  • hyperedge_to_add (Hyperedge) – sub-hyperedge to add

  • in_node (Node) – node to which sub-hyperedge should be added

static add_sub_node(node_to_add, in_node)

static method adding a child node to a given node

Parameters
  • node_to_add (Node) – sub-node to add

  • in_node (Node) – node to which sub-node should be added

build_model(nb_processes: int = 1)

bound method generating the matrices of the optimization model

Parameters

nb_processes (int) – number of processes used for model generation

static change_node_name_in_hyperedge(hyperedge, old_node_name, new_node_name)

static method changing the name of a node appearing in the constraints of a given hyperedge

Parameters
  • hyperedge (Hyperedge) – Hyperedge in which node names should be changed

  • old_node_name (str) – previous node name

  • new_node_name (str) – new node name

static change_type_variable_in_node(node, variable_name: str, variable_type)

static method changing the type of a variable

Parameters
  • node (Node) – node to which variable that should be modified belongs

  • variable_name (str) – variable name

  • variable_type (VariableType) – new variable type (either External or Internal)

static create_parameter(parameter_name, value)

static method that returns a parameter whose name is given by parameter_name and expression by value

Parameters
  • parameter_name (str) – parameter name

  • value (float/int/list<int/float>) – value of parameter

Returns

param (Parameter) – parameter created

static get_object_in_node(in_node, *node_identifier: str, wanted_type=None)

static method returning a node or a hyperedge given an ancestor node

Parameters
  • in_node (Node) – node to which the sub-node is expected to belong

  • node_identifier (list <str>) – list of ancestor node names, with first name corresponding to first sub-node and last name corresponding to node to retrieve

  • wanted_type (Class Type) – either Node or Hyperedge depending on the type of the object considered

Returns

retrieved_object (Node/Hyperedge) – retrieved node or hyperedge

get_timehorizon()

bound method returning the value of the time horizon

Returns

value (int) – length of time horizon considered

static import_all_nodes_and_edges(filename, cache=True)

static method importing all nodes and hyperedges contained in a file

Parameters
  • filename (str) – path to GBOML input file

  • cache (bool) – activate caching all the hypergraphs read during import by default set to true

Returns
  • all_nodes (list) – list of nodes contained in file

  • all_hyperedges (list) – list of hyperedges contained in file

  • all_global_param (list) – list of global parameters in file

static import_hyperedge(filename: str, *imported_hyperedge_identifier: str, new_hyperedge_name: str = '', copy=True, cache=True)

static method importing a hyperedge from a GBOML input file

Parameters
  • filename (str) – path to GBOML input file

  • imported_hyperedge_identifier (list <str>) – list of ancestor node names and hyperedge name (used for depth- first traversal)

  • new_hyperedge_name (str) – new hyperedge identifier (for re-naming purposes, optional)

  • copy (bool) – keyword argument defining whether a shallow or deep copy of the imported node is created (defaults to True, which produces a deepcopy)

  • cache (bool) – activate caching all the hypergraphs read during import by default set to true

Returns

imported_hyperedge (Hyperedge) – imported hyperedge

static import_node(filename: str, *imported_node_identifier: str, new_node_name: str = '', copy=True, cache=True)

static method importing a node from a GBOML input file

Parameters
  • filename (str) – path to GBOML input file

  • imported_node_identifier (list <str>) – list of ancestor node names and node name (used for depth-first traversal)

  • new_node_name (str) – new identifier of node (for re-naming purposes, optional)

  • copy (bool) – keyword argument defining whether a shallow or deep copy of the imported node is created (defaults to True, which produces a deepcopy)

  • cache (bool) – activate caching all the hypergraphs read during import by default set to true

Returns

imported_node (Node) – imported node

static modify_parameter_value(parameter, value)

Modify the value of parameter

Parameters
  • parameter (Parameter) – parameter to modify

  • value (int|float|list<float/int>) – value associated to the parameter

Returns:

static redefine_parameters_from_keywords(node_or_hyperedge, **kwargs)

static method re-defining parameter values from keyword arguments

Parameters
  • node_or_hyperedge (Node/Hyperedge) – Node/Hyperedge in which parameters should be re-defined

  • kwargs (tuple <str, value>) – tuple of parameters name, value

static redefine_parameters_from_list(node_or_hyperedge, list_parameters: list, list_values: list)

static method re-defining parameter values from a list

Parameters
  • node_or_hyperedge (Node/Hyperedge) – Node/Hyperedge in which parameters should be re-defined

  • list_parameters (list <str>) – list of parameter names

  • list_values (list <float> | list <float> | <str>) – list of parameter values

static remove_constraint(node_or_hyperedge, *to_delete_constraints_names)

static method removing constraints from a node/hyperedge

Parameters
  • node_or_hyperedge (Node/Hyperedge) – Node/Hyperedge from which constraints should be removed

  • to_delete_constraints_names (list <str>) – names of constraints to remove

static remove_objective_in_node(node, *to_delete_objectives_names)

static method removing objectives from a node

Parameters
  • node (Node/Hyperedge) – node from which objectives should be removed

  • to_delete_objectives_names (list <str>) – names of objectives to remove

static rename(node_or_hyperedge, new_name)

static method re-naming a node or hyperedge

Parameters
  • node_or_hyperedge (Node/Hyperedge) – node or hyperedge to be re-named

  • new_name (str) – new name

static set_parsing_cache_limit(size)

sets a limit to the global cache.

Parameters

size – The cache size

set_timehorizon(value)

bound method setting the time horizon to a specified value

Parameters

value (int) – length of time horizon considered

solve_cbc(opt_file=None, opt_dict=None)

bound method solving the flattened optimization problem with Cbc

Parameters
  • opt_file (str) – filename of file containing the optimization parameters

  • opt_dict (dict) – dictionary containing the optimization parameters the key must be the parameter to tune the value a tuple of the <type, value> example: {“gap”: [“double”, 0.5]

Returns
  • solution (ndarray) – flattened solution

  • objective (flat) – float of the objective value

  • status (str) – solver exit status

  • solver_info (dict) – dictionary storing solver information

solve_clp()

bound method solving the flattened optimization problem with Clp

Returns
  • solution (ndarray) – flattened solution

  • objective (flat) – float of the objective value

  • status (str) – solver exit status

  • solver_info (dict) – dictionary storing solver information

solve_cplex(opt_file: str = None, details=False, opt_dict=None)

bound method solving the flattened optimization model with CPLEX

Parameters
  • opt_file (str) – path to an optimization parameters file

  • details (bool) – get variables and constraints information

  • opt_dict (dict) – dictionary containing the optimization parameters

Returns
  • solution (ndarray) – flattened solution

  • objective (float) – objective value

  • status (str) – solver exit status

  • solver_info (dict) – dictionary storing solver information

  • constraints_information (dict) – dict of additional information concerning constraints

  • variables_information (dict) – dict of additional information concerning variables

solve_dsp(algorithm='dw')

bound method solving the optimization model with DSP

Parameters

algorithm (str) – algorithm selected (“dw” for Dantzig-Wolfe and “de” for extensive form solve)

Returns
  • solution (ndarray) – flattened solution

  • objective (float) – objective value

  • status (str) – solver exit status

  • solver_info (dict) – dictionary of solver information

solve_gurobi(opt_file: str = None, details=False)

bound method solving the flattened optimization model with Gurobi

Parameters
  • opt_file (str) – path to an optimization parameters file

  • details (bool) – get variables and constraints information

Returns
  • solution (ndarray) – flattened solution

  • objective (float) – objective value

  • status (str) – solver exit status

  • solver_info (dict) – dictionary storing solver information

  • constraints_information (dict) – dict of additional information concerning constraints

  • variables_information (dict) – dict of additional information concerning variables

solve_highs()

bound method solving the flattened optimization problem with Highs

Returns
  • solution (ndarray) – flattened solution

  • objective (flat) – float of the objective value

  • status (str) – solver exit status

  • solver_info (dict) – dictionary storing solver information

solve_xpress(opt_file: str = None, details=False)

bound method solving the flattened optimization model with Xpress

Parameters
  • opt_file (str) – path to an optimization parameters file

  • details (bool) – get variables and constraints information

Returns
  • solution (ndarray) – flattened solution

  • objective (float) – objective value

  • status (str) – solver exit status

  • solver_info (dict) – dictionary storing solver information

  • constraints_information (dict) – dict of additional information concerning constraints

  • variables_information (dict) – dict of additional information concerning variables

turn_solution_to_dictionary(solver_data, status, solution, objective, constraint_info=None, variables_info=None)

bound method converting the flat solution to a structured dictionary

Parameters
  • solver_data (dict) – dictionary of solver information

  • status (str) – solver exit status

  • solution (ndarray) – flattened solution

  • objective (float) – objective value

  • constraint_info (dict) – dict of additional information concerning constraints

  • variables_info (dict) – dict of additional information concerning variables

Returns

gathered_data (dict) – structured dictionary containing all the solution information

turn_solution_to_list(solution, constraints_info=None)

bound method converting the flat solution to a list of <name, value> tuples

Parameters
  • solution (ndarray) – flattened solution

  • constraints_info (dict) – dict of additional information concerning constraints

Returns

output_list (list) – list of <name, value> tuples