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