Module docplex.cp.utils_visu

An add-on to matplotlib for easy display of CP Optimizer scheduling solutions and structures.

It requires to have external libraries numpy and matplotlib already installed in the Python environment.

Detailed description

docplex.cp.utils_visu.function(name=None, segments=None, origin=None, horizon=None, style='segment', color=None)

Creates a new function in the current function panel.

If no current panel exists of if the current panel is not a function panel, a new function panel will be automatically created and set as the current panel.

Parameters:

• name (str) – Name of the function.
• segments (list or CpoFunction or CpoStateFunctionSolution) – Explicit list of segments of the function (see ‘segment’) or segments of the specified CpoFunction or CpoStateFunctionSolution instance.
• origin (int) – Value of the origin of function.
• horizon (int) – Value of the horizon of function.
• style ('segment' or 'line' or 'area' or 'interval') – Display style of the function.
• color (int or str) – Color of the function

Note that the ‘origin’ and ‘horizon’ of the x-axis of the timeline are automatically adjusted depending on the content of the timeline. In particular, their the scope will be automatically enlarged if the content does not fit into the original [‘origin’,’horizon’] interval.

When the color of a function is specified as an integer color index, the visualization will automatically allocate a color to this index and will ensure that all elements with this color index gets the same color all across the timeline.

Examples:

function(name='F1',
         segments=[(0,10,20),(10,20,0),(20,40,10)],
         style='area',
         color=2)
function(name='F2',
         segments=[(0,10,20,0),(10,20,0),(20,INT_MAX,7.5,1.0)],
         style='segment',
         color='blue')

docplex.cp.utils_visu.interval(*args)

Creates a new interval.

If the current panel is a sequence panel, the created interval will be added to the current sequence in this sequence panel. Otherwise, the interval will be added in an interval panel, such an interval panel will be automatically created if no current panel exists or the current panel is a function panel.

Parameters:args –

The following combination of arguments is allowed:

• (int start, int end, int|string color, string name)
• (int start, int end, int|string color)
• (int start, int end)
• (CpoIntervalVarSolution cpointerval, int|string color, string name)
• (CpoIntervalVarSolution cpointerval, int|string color)
• (CpoIntervalVarSolution cpointerval)

When the color of an interval is specified as an integer color index, the visualization will automatically allocate a color to this index and will ensure that all elements with this color index gets the same color all across the timeline.

Examples:

interval(0, 20, 1, 'Job1')
interval(10, 35, 'darkred')
interval(itvsol)

docplex.cp.utils_visu.is_visu_enabled()

Check if visu is enabled and print a message if not.

Returns:True if visu is enabled

docplex.cp.utils_visu.matrix(name=None, matrix=None, tuples=None, cpomatrix=None)

Create a new matrix figure and set it as the current figure.

One and only one among the arguments ‘matrix’, ‘tuples’ or ‘cpomatrix’ should be provided to specify the values of the matrix.

Parameters:

• name (str) – Name of the figure.
• matrix (list) – Values of the matrix specified as a list of lists of integers.
• tuples (list) – Values of the matrix specified as a list of tuples (i,j,vij). Unspecified matrix cells have value 0 by default.
• cpomatrix (CpoTransitionMatrix) – Values of the matrix specified as an instance of CpoTransitionMatrix.

Examples:

matrix(name="M1",
       tuples=[(i,j,abs(i-j)) for i in range(50) for j in range(50)])

docplex.cp.utils_visu.naming(function=None)

Sets a name formatting function.

The names of the displayed objects (intervals) are sometimes too long or ill-formatted for an elegant display. This function allows setting a name formatting function that will be used to display all intervals.

Parameters:function – The name formatter function. If not None, this function should take an ‘str’ as argument and return an ‘str’.

Example:

naming(lambda name: name.upper()) # Display all names in upper case
naming(lambda name: name[0:3])    # Trunk names to first 3 characters

docplex.cp.utils_visu.panel(name=None)

Creates a new panel in the current timeline figure.

If no current timeline figure exists, one will be automatically created. The type of the created panel will depend on subsequent commands:

• Command -> Panel type
• sequence -> sequence panel
• transition -> sequence panel
• interval -> interval panel
• function -> function panel
• segment -> function panel

Parameters:name (str) – Name of the panel.

docplex.cp.utils_visu.pause(*args)

Creates a new pause interval.

If the timeline has a current panel, the pause(s) will be local to this current panel, otherwise, if the pause is created before any panel, the pause is a general pause of the timeline and will therefore be displayed in all the (future) panels of the timeline.

If the argument is an instance of CpoFunction, pauses will be created for all segments of the function with value 0.

Parameters:args –

The following combination of arguments is allowed:

• (int start, int end)
• (CpoIntervalVarSolution cpointerval)
• (CpoFunction)

docplex.cp.utils_visu.segment(*args)

Creates a new segment.

If the current panel is a sequence panel, the created segment will be added to the current sequence in this sequence panel. Otherwise, the segment will be added in the current function of a function panel. If such a function / function panel does not currently exist, it will be automatically created.

Parameters:args –

The following combination of arguments is allowed:

• (int start, int end, int vstart, int vend, string name)
• (int start, int end, int vstart, int vend)
• (int start, int end, int vstart)
• (CpoIntervalVarSolution cpointerval, int vstart, int vend, string name)
• (CpoIntervalVarSolution cpointerval, int vstart, int vend)
• (CpoIntervalVarSolution cpointerval, int vstart)

If start=INT_MIN and end=INT_MAX, then you should have vstart=vend and the segment represents the constant function f=vstart on [INT_MIN,INT_MAX). Otherwise:

• When start>INT_MIN, vstart denotes the value of the segment at its start.
• When start=INT_MIN, vstart denotes the slope of the segment at its start.
• When end<INT_MAX, vend denotes the value of the segment at its end.
• When end=INT_MAX, vend denotes the slope of the segment at its end.
• When vend is not specified, it means the segment has a constant value vstart (step).

Examples:

segment(0, 20, 10, 20)          # value at x=10: 15
segment(0, 20, 10)              # value at x=10: 10
segment(INT_MIN,20,-0.5,7.5)    # value at x=10: 12.5
segment(0, INT_MAX, 0, 0.1)     # value at x=10: 1.0
segment(INT_MIN,INT_MAX, 3)     # value at x=10: 3

docplex.cp.utils_visu.sequence(name=None, intervals=None, transitions=None, segments=None)

Creates a new sequence in the current sequence panel.

If no current panel exists of if the current panel is not a sequence panel, a new sequence panel will be automatically created and set as the current panel.

Parameters:

• name (str) – Name of the sequence.
• intervals (list or CpoSequenceVarSolution or CpoStateFunctionSolution) – Explicit list of intervals of the sequence (see ‘interval’) or intervals of the specified CpoSequenceVarSolution or CpoStateFunctionSolution instance.
• transitions (list) – list of transitions of the sequence (see ‘transition’).
• segments (list or CpoFunction or CpoStateFunctionSolution) – Explicit list of segments of the sequence (see ‘segment’) or segments of the specified CpoFunction or CpoStateFunctionSolution instance.

Examples:

sequence(name='Machine1',
         intervals=[(0,10,1,'Job1'),(15,35,2,'Job2')],
         transitions=[(10,13)])

docplex.cp.utils_visu.show(object=None, name=None, origin=None, horizon=None, pngfile=None)

Shows the active figures.

Active figures are all the ones that have been created since last call to function ‘show’. Additionally, this function can use the default display to display the CP Optimizer object passed as argument.

Parameters:

• (CpoModelSolution or CpoTransitionMatrix or CpoFunction or (object) – CpoStateFunctionSolution): object to be displayed using default display.
• name (str) – Name of the object in the display.
• origin (int) – Value of the origin of the x-axis of the timeline.
• horizon (int) – Value of the horizon of the x-axis of the timeline.
• file (string) – Name of the file where store the figure instead of displaying it on the screen

docplex.cp.utils_visu.timeline(name=None, origin=None, horizon=None, pauses=None)

Create a new timeline figure and set it as the current figure.

Parameters:

• name (str) – Name of the figure.
• origin (int) – Value of the origin of the x-axis of the timeline.
• horizon (int) – Value of the horizon of the x-axis of the timeline.
• pauses (list or CpoFunction) – Pause intervals of the timeline. Given as and explicit list of pauses (see ‘pause’) or specified by the intervals where the CpoFunction instance has value 0.

Note that the ‘origin’ and ‘horizon’ of the x-axis of the timeline are automatically adjusted depending on the content of the timeline. In particular, their the scope will be automatically enlarged if the content does not fit into the original [‘origin’,’horizon’] interval.

Pauses specified at the level of the timeline are general pauses that will be displayed in all the panels of the timeline.

docplex.cp.utils_visu.transition(*args)

Creates a new transition interval in the current sequence panel.

If no current panel exists of if the current panel is not a sequence panel, a new sequence panel will be automatically created and set as the current panel.

Parameters:args –

The following combination of arguments is allowed:

• (int start, int end)
• (CpoIntervalVarSolution cpointerval)

Examples:

transition(0, 20)
transition(itvsol)