DecisionProgramming.Diagram module

Interface for Jump functionality necessary for optimizing models generated from diagrams.

class DecisionProgramming.Diagram.CompatiblePaths(diagram, decision_strategy, fixed=None)[source]

Bases: DecisionProgramming.juliaUtils.JuliaName

Interface for iterating over paths that are compatible and active given influence diagram and decision strategy.

Parameters

diagram: dp.Diagram: An influence diagram.
decision_strategy: dp.DecisionStrategy: A decision strategy for the diagram.
fixed: dp.FixedPath: Describes states that are held fixed.

class DecisionProgramming.Diagram.DecisionStrategy(decision_variables)[source]

Bases: DecisionProgramming.juliaUtils.JuliaName

Extract values for decision variables from solved decision model.

Parameters

decision_variables: Decision variables from a solved model

class DecisionProgramming.Diagram.DecisionVariables(model, diagram, names=False, name='z')[source]

Bases: DecisionProgramming.juliaUtils.JuliaName

Create decision variables and constraints.

Parameters

model: dp.Model: A JuMP Model object
diagram: dp.InfluenceDiagram: A DecisionProgramming Diagram object
names: bool: Use names or have anonymous Jump variables
name: str: Prefix for predefined decision variable naming convention

decision_strategy()[source]

Extract the optimal decision strategy.

Returns

dp.DecisionStrategy: The optimal decision strategy wrapped in a Python object.

class DecisionProgramming.Diagram.ExpectedValue(model, diagram, pathcompatibility)[source]

Bases: DecisionProgramming.juliaUtils.JuliaName

An expected value object JuMP can minimize on maximize

Parameters

model: Model
diagram: Diagram
pathcompatibility: PathCompatibilityVariables

class DecisionProgramming.Diagram.ExpressionPathUtilities(model, diagram, expression, path_name='s')[source]

Bases: DecisionProgramming.juliaUtils.JuliaName

An expression that can be used to set path utilities.

Parameters

model: dp.Model: A JuMP Model object
diagram: dp.InfluenceDiagram: The influence diagram the model was constructed with.
expression: string: A JuMP expression that describes the path utilities (see the contingent portfolio analysis page in examples).

class DecisionProgramming.Diagram.FixedPath(diagram, paths)[source]

Bases: DecisionProgramming.juliaUtils.JuliaName

Describes fixed paths in an influence diagram.

Parameters

diagram: An InfluenceDiagram: The influence diagram.
node_values: dict: Dictionary with node names as keys and the fixed value as the corresponding values.

class DecisionProgramming.Diagram.ForbiddenPath(diagram, nodes, states)[source]

Bases: DecisionProgramming.juliaUtils.JuliaName

Describes forbidden paths through an influence diagram.

Parameters

diagram: An InfluenceDiagram: The influence diagram.
nodes: List of strings: List of node names connected by the forbidden paths
values: List of tuples of strings: List of states of the connected nodes that are forbidden

class DecisionProgramming.Diagram.InfluenceDiagram[source]

Bases: DecisionProgramming.juliaUtils.JuliaName

Holds information about the influence diagram, including nodes and possible states.

See the latest documentation for the Julia type at (https://gamma-opt.github.io/DecisionProgramming.jl/dev/api/).

add_node(node)[source]

Add a node to the diagram

Parameters

nodeChanceNode, DecisionNode, or ValueNode

build_random(n_C, n_D, n_V, m_C, m_D, states, seed=None)[source]

Generate random decision diagram with n_C chance nodes, n_D decision nodes, and n_V value nodes. Parameter m_C and m_D are the upper bounds for the size of the information set.

Parameters

n_C: Int: Number of chance nodes.
n_D: Int: Number of decision nodes.
n_V: Int: Number of value nodes.
m_C: Int: Upper bound for size of information set for chance nodes.
m_D: Int: Upper bound for size of information set for decision nodes.
states: List if integers: The number of states for each chance and decision node is randomly chosen from this set of numbers.

conditional_value_at_risk(path_compatibility_variables, alpha, probability_scale_factor)[source]

Create a conditional value-at-risk (CVaR) objective.

Parameters

model: Model: JuMP model into which variables are added.
x_s: PathCompatibilityVariables: Path compatibility variables.
alpha: Float64: Probability level at which conditional value-at-risk is optimised.
probability_scale_factor:Float64: Adjusts conditional value at risk model to be compatible with the expected value expression if the probabilities were scaled there.

construct_probability_matrix(node)[source]

Return a probability matrix with appriate dimensions for a given node and zero values.

Parameters

node: String: The name of a ChanceNode.

Returns

dp.ProbabilityMatrix: A probabity matrix with zero values.

construct_utility_matrix(node)[source]

Return a utility matrix with appriate dimensions for a given node and values set to negative infinity.

Parameters

node: String: The name of a UtilityMatrix.

Returns

dp.UtilityMatrix: A utility matrix with values set to negative infinity.

decision_variables(model)[source]

Construct the decision variables for a given model and this diagram.

Parameters

model: dp.Model: A model constructed for this diagram.

Returns

dp.DecisionVariables: The set of decision variables for the model.

expected_value(model, path_compatibility_variables=None)[source]

Return the expected value given the optimal decision strategy after optimizing the model.

Parameters

model: dp.Model: A model constructed for this diagram.
path_compatibility_variables: dp.PathCompatibilityVariables (optional): PathCompatibilityVariables generated for this model, usually using diagram.path_compatibility_variables.

Returns

dp.ExpectedValue: A dp.ExpectedValue object describing the expected value for the optimal decision strategy.

fixed_path(node_values)[source]

Create a fixed path object, used to force ChangeNodes to have given values.

Parameters

node_values: dict: Dictionary with node names as keys and the fixed value as the corresponding values.

Returns

dp.FixedPath: A dp.FixedPath object.

forbidden_path(nodes, values)[source]

Create a ForbiddenPath object used to describe invalid paths through the diagram.

Parameters

nodes: List of strings: List of node names connected by the forbidden paths
values: List of tuples of strings: List of states of the connected nodes that are forbidden

Returns

dp.ForbiddenPath: A dp.ForbiddenPath object.

generate(default_probability=True, default_utility=True, positive_path_utility=False, negative_path_utility=False)[source]

Generate the diagram once nodes, probabilities and utilities have been added.

Parameters

default_probability: bool = True: Choice to use default path probabilities
default_utility: bool = True: Choice to use default path utilities
positive_path_utilitybool = False: Choice to use a positive path utility translation
negative_path_utilitybool = False: Choice to use a negative path utility translation

generate_arcs()[source]: Generate arc structures using nodes added to influence diagram, by ordering nodes, giving them indices and generating correct values for the vectors Names, I_j, states, S, C, D, V in the influence digram. Abstraction is created and the names of the nodes and states are only used in the user interface from here on.

index_of(name)[source]

Find index of a given node.

Parameters

node: String: The name of a node

Returns

Integer: The index of the node in the diagram

lazy_probability_cut(path_compatibility_variables)[source]

Add a probability cut to the model as a lazy constraint.

Parameters

path_compatibility_variables: dp.PathCompatibilityVariables: A set of path compatibility variables constructed for this diagram.

num_states(node)[source]

Find the number of states a given node has.

Parameters

node: String: The name of a node

Returns

Integer: The number of states the given node has

path_compatibility_variables(model, decision_variables=None, names=False, name='x', forbidden_paths=None, fixed=None, probability_cut=True, probability_scale_factor=1.0)[source]

Construct the path compatibility variables for a given model and this diagram.

Parameters

model: dp.Model: A model constructed for this diagram.
decision variables: dp.DecisionVariables (optional): DecisionVariables constructed for this model.
names: Bool (optional)
name: String (optional)
forbidden_paths: List of dp.ForbiddenPath variables (optional)
fixed: List of dp.FixedPath variables (optional)
probability_cut: Bool (optional)
probability_scale_factor: Number (optional)

Returns

dp.PathCompatibilityVariables: The set of path compatibility variables for the model.

random_probabilities(node, n_inactive=0, seed=None)[source]

Generate random probabilities for a chance node.

Parameters

node: dp.ChanceNode: Random probabilities will be assigned to this node.
n_inactive: Int: Number of inactive states

random_utilities(node, low=- 1.0, high=1.0, seed=None)[source]

Generate random utilities for a value node.

Parameters

node: dp.ValueNode: Random utilities are generated for this node
low: float: Lower bound for random utilities
high: float: Upper bound for random utilities
seed: int: Seed for the random number generator

set_path_utilities(expressions)[source]

Use given expression as the path utilities of the diagram.

Parameters

expressions: ExpressionPathUtilities: A set of JuMP expression.

set_probabilities(node, matrix)[source]

Set the probabilities of a ChanceNode

Parameters

nodestr: The name of a ChanceNode. The probability matrix of this node is returned.
matrixProbabilityMatrix or Numpy array: The probability matrix that replaces the current one. May be a ProbabilityMarix of a Numpy array.

set_utility(value, matrix)[source]

Set the utilities of a ValueNode

Parameters

nodestr: The name of a ValueNode. The probability matrix of this node is returned.
matrixNumpy array: The probability matrix that replaces the current one.

state_probabilities(decision_strategy)[source]

Extract the state probabilities as a dp.StateProbabilities object.

Parameters

decision_strategy: dp.DecisionStrategy: A decision strategy. A decision strategy can be constructed using the dp.DecisionVariables.decision_strategy method.

Returns

dp.StateProbabilities: A dp.StateProbabilities object containing information about the probabilites of each state given the decision strategy.

utility_distribution(decision_strategy)[source]

Extract the utility distribution as a dp.UtilityDistribution object.

Parameters

decision_strategy: dp.DecisionStrategy: A decision strategy. A decision strategy can be constructed using the dp.DecisionVariables.decision_strategy method.

Returns

dp.UtilityDistribution: Describes the distribution of utilities given the decision strategy.

class DecisionProgramming.Diagram.PathCompatibilityVariables(model, diagram, decision_variables, names=False, name='x', forbidden_paths=None, fixed=None, probability_cut=True, probability_scale_factor=1.0)[source]

Bases: DecisionProgramming.juliaUtils.JuliaName

Create path compatibility variables and constraints

Parameters

model: Model: JuMP model into which variables are added.
diagram: InfluenceDiagram: Influence diagram structure.
decision_variables: DecisionVariables: A set of decision variables for the diagram.
names: bool: Use names or have JuMP variables be anonymous.
name: str: Prefix for predefined decision variable naming convention.
forbidden_paths: list of ForbiddenPath objects:: The forbidden subpath structures. Path compatibility variables will not be generated for paths that include forbidden subpaths.
fixed: FixedPath: Path compatibility variable will not be generated for paths which do not include these fixed subpaths.
probability_cut: bool: Includes probability cut constraint in the optimisation model.
probability_scale_factor: float: Adjusts conditional value at risk model to be compatible with the expected value expression if the probabilities were scaled there.

Attributes

diagram: InfluenceDiagram: An influence diagram.
decision_variables: DecisionVariables: A set of decision variables for the diagram

class DecisionProgramming.Diagram.Paths(states, fixed=None)[source]

Bases: DecisionProgramming.juliaUtils.JuliaName

Iterate over paths in lexicographical order.

Parameters

states: List of strings: List of paths to connect
fixed: dp.FixedPath: Describes states that are held fixed.

class DecisionProgramming.Diagram.ProbabilityMatrix(diagram, node)[source]

Bases: DecisionProgramming.juliaUtils.JuliaName

Construct an empty probability matrix for a chance node.

Parameters

diagram: Diagram: The influence diagram that contains the node
nodestr: The name of a ChanceNode. The probability matrix of this node is returned.

size()[source]: Return the size of the nodes information set.

class DecisionProgramming.Diagram.StateProbabilities(diagram, decision_strategy)[source]

Bases: DecisionProgramming.juliaUtils.JuliaName

Extract state propabilities from a solved model

Parameters

diagram: Diagram: An influence diagram
decision_strategy: dp.DecisionStrategy: A decision strategy created for the diagram.

print(nodes)[source]: Print the state probabilities.

print_decision_strategy()[source]: Print the decision strategy.

class DecisionProgramming.Diagram.UtilityDistribution(diagram, decision_strategy)[source]

Bases: DecisionProgramming.juliaUtils.JuliaName

Extract utility distribution from a solved model

Parameters

diagram: Diagram: The diagram of a solved model
decision_strategy: DecisionStrategy: A decision strategy extracted from a solved model.

conditional_value_at_risk(alpha)[source]: Print the conditional value at rist

print_distribution()[source]: Print the utility distribution.

print_risk_measures(alpha, format='%f')[source]: Print risk measures.

print_statistics()[source]: Print statistics about the utility distribution.

value_at_risk(alpha)[source]: Print the value at risk.

class DecisionProgramming.Diagram.UtilityMatrix(diagram, node)[source]

Bases: DecisionProgramming.juliaUtils.JuliaName

Construct an empty probability matrix for a chance node.

Parameters

diagram: Diagram: The influence diagram that contains the node
nodestr: The name of a ChanceNode. The probability matrix of this node is returned.