Formulation API Methods

The Formulation API is used for making changes to the formulation, such as adding and removing constraints and objectives.

This page discusses:

getFormulation()

This method gets the entire formulation as a single dictionary-like object.

Arguments
None.
Return Value
Returns a dictionary-like object containing a list of all objectives keyed to objectives and a list of all constraints keyed to constraints.

setFormulation(Dictionary formulation)

This method sets the formulation based on a JSON object describing the entire formulation.

Arguments
  • formulation: A dictionary-like object defining all constraints and objectives on the case.
  • formulation schema: Formulation Schema
Return Value
Returns a dictionary-like object containing a list of all objectives keyed to objectives and a list of all constraints keyed to constraints.
setFormulation() expects an object with the same structure as the object it returns.

selectConstraints(Callable selector)

This method selects all constraints matching a specified selector.

Arguments
selector: An object that can be called with Python.
Return Value
Returns a list-like Python object containing all constraints matching the selector.
The selector is passed each constraint in the data set. The following example selects all constraints with the type LESS_THAN:
def lessThanTest(constraint):
    return constraint["type"] == "LESS_THAN"

ltConstraints = FormulationAPI.selectConstraints(lessThanTest)

selectObjectives(Callable selector)

This method selects all objectives matching a specified selector.

Arguments
selector: An object that can be called with Python
Return Value
Returns a list-like Python object containing all objectives matching the selector.
The selector is passed each objective in the data set. The following example selects all objectives with the type MAXIMIZE:
def maximizeTest(objective):
    return objective["type"] == "MAXIMIZE"

maxObjectives= FormulationAPI.selectObjectives(maximizeTest)

removeConstraint(String paramId, String type)

This method removes a constraint specified by a dictionary-like object containing parameter ID and type from the formulation.

Arguments
  • paramId: A string identifying the parameter for which the constraint to be removed is defined.
  • type: The type attribute of the constraint to be removed.
Return Value
None.
paramId is the id attribute on the parameter objects used by methods in the Parameter API.

addConstraint(String paramId, String type, Number boundValue, List<Number> range)

This method adds a constraint specified by a dictionary-like object containing the parameter ID, type, and value to the formulation.

Arguments
  • paramId: A string identifying the parameter for which the constraint should be defined.
  • type: The type of constraint to be added. Valid types are LESS_THAN, GREATER_THAN, and IN_RANGE.
  • boundValue: The bound value for LESS_THAN and GREATER_THAN constraints. Invalid for other constraint types.
  • range: A list containing exactly two numbers defining the range for IN_RANGE constraints. Invalid for other constraint types.
Return Value
None.
paramId is the id attribute on the parameter objects used by methods in the Parameter API.

addObjective(String paramId, String type, Number value, Number rank)

This method adds an objective specified by a JSON object containing parameter ID, type, rank, and value to the formulation.

Arguments
  • paramId: A string identifying the parameter for which the objective will definedbe .
  • type: The type of objective to be added. Valid types are MAXIMIZE, MINIMIZE, AVOID, and TARGET.
  • value: The value of the objective. Valid only for objectives of types TARGET and AVOID, for which the value parameter must be supplied.
  • rank: Optional parameter defining the rank of the objective.
Return Value
Returns a dictionary-like object describing the newly created objective.
paramId is the id attribute on the parameter objects used by methods in the Parameter API.

removeObjective(String paramId)

This method removes an objective specified by a parameterID from the formulation.

Arguments
paramId: A string identifying the parameter for which any existing objective will be removed.
Return Value
None.
paramId is the id attribute on the parameter objects used by methods in the Parameter API.

getObjectiveIterator()

This method gets the ID for an iterator over the set of objectives.

Arguments
None.
Return Value
Returns the string ID identifying the iterator.

getConstraintIterator()

This method gets the ID for an iterator over the set of constraints.

Arguments
None.
Return Value
Returns the string ID identifying the iterator.

next(String iteratorId)

This method gets the next item for either a constraint or an objective iterator.

Arguments
iteratorId: The string ID of an iterator obtained with getObjectiveIterator() or getConstraintIterator().
Return Value
Returns a dictionary-like object describing the retrieved objective or constraint.

hasNext(String iteratorId)

This method verifies if a specified iterator has a next item.

Arguments
iteratorId: The string ID of an iterator obtained with getObjectiveIterator() or getConstraintIterator().
Return Value
Returns true if the iterator has at least one additional entry.

getConstraintsForParameter(String paramId)

This method gets all constraints for a specified parameter.

Arguments
paramId: String defining the parameter for which constraints are being requested
Return Value
Returns a list-like object containing dictionaries defining each constraint associated with the specified parameter.
paramId is the id attribute on the parameter objects used by methods in the Parameter API.

getObjectiveForParameter(String paramId)

This method gets all objectives for a specified parameter.

Arguments
paramId: A string defining the parameter for which the objective is being requested.
Return Value
Returns a dictionary-like object defining the objective associated with the specified parameter.
paramId is the id attribute on the parameter objects used by methods in the Parameter API.