IlcDiscreteEnergy

An instance of the class IlcDiscreteEnergy represents a resource available as a certain amount of energy (for example, in watt-hours or human-months) over certain time buckets (for example, minutes, hours, months, or years). The available energy of a time bucket is used by the activities that are executed within that time bucket. As a consequence, constraints exist on the energy capacity of the discrete energy resource.

For example, let's assume that each unit of time corresponds to an hour, and that we have defined a discrete energy resource that has a time step of 24 (corresponding to a day), and energy 10 (machine-hours). Then if we have an activity of duration 3 (hours) that requires the resource with capacity 2 (machines), it uses energy of 6 (machine-hours). Thus, if this activity is scheduled on the first day, the remaining energy for that first day is 4 (machine-hours).

An instance of the class IlcDiscreteEnergy differs from an instance of the class IlcDiscreteResource in that it uses the concept of energy, whereas IlcDiscreteResource uses the concept of instantaneous capacity. However, when the time step of the timetables is 1, the energy over an interval corresponds to the instantaneous capacity, and so in that case, there is no difference between the two classes. The same is true in the case of a time table with breaks which, in the case of a time bucket of duration 1, either a break fills the bucket, or the duration of breaks in the bucket is zero.

Energy Relaxation

A common use of discrete energy is to relax the capacity constraint of a discrete resource. Instead of enforcing an instantaneous available capacity, the energy relaxation enforces that the average capacity over a time bucket cannot be exceeded. The corresponding energy is defined as the product of this average instantaneous capacity times the duration of the time bucket. An advantage is that if several activities with different start and end times share the same time bucket, the average complexity of the propagation decreases.

In a more formal way, let act be an activity, and svar, evar and dvar be the start, end, and duration variables of act. So we have evar = svar + dvar. Now let R be an energy resource, bkt a time bucket of duration bktdur, bktmin the time bucket start time, and bktmax the end time. Let cvar be the capacity required by act on R.

The duration of the execution of act in the time bucket bkt is:

 d(act, bkt) =  min(bktdur, dvar, evar - bktmin, bktmax - svar).

The energy required by act on bkt is E(act, bkt) = d(act, bkt)*cvar.

The discrete energy resource constraint enforces that, for each time bucket bkt, the sum over all activities of E(act, bkt) is less than or equal to the maximum available energy in bkt.

One notices that if the bucket encompasses the activity execution, then d(act, bkt) is reduced to dvar, and the required energy is dvar*cvar. When the activity execution overlaps the time bucket, d(act, bkt) = bktdur = bktmax - bktmin, and the required energy is (bktmax - bktmin)*cvar.

The last remark reveals that the energy relaxation has a drawback in the case of breakable activities. The effective required energy should only depend upon the processing time, and not the entire duration. For example, in the case of a time bucket that contains the entire activity execution, dvar*cvar overestimates the energy that is effectively required, by failing to subtract the unused capacity during break times. Likewise, in the case of an activity execution that overlaps the time bucket, (bktmax - bktmin)*cvar overestimates the energy required, because breaks can take place between bktmin and bktmax.

This energy relaxation also has a drawback in the case of unary resources. For example, suppose a bucket of duration 6, and a break at the end of the bucket of duration 2. There are two ways to determine the energy. One way is to state that the net bucket energy is 6 - 2 = 4. However, a breakable activity using 1 unit of energy per unit duration, with a duration greater than 6, could not overlap the bucket, since only 4 units of energy are available over 6 time units. This is incorrect as such an activity should be able to overlap the bucket and suspend processing during the break. Alternatively, we could state that the break does not use any energy, thus allowing 6 energy units in the first 4 time units of the bucket. However, this would allow two activities of duration 3 to exist within the bucket. Recall, however, that this energy resource is a relaxation of a unary resource. Having two activities of duration 3 plus a break of 2 within an interval of size 6 clearly violates the unary resource. If possible, we would like to have a relaxation that would not allow such a "solution."

To avoid these drawbacks, Scheduler Engine offers a relaxation in the case of an energy resource with breaks and breakable activities. The main idea is to describe the bucket as containing a break duration and an energy available outside the break to process the activities. A relaxation of the processing time in the bucket for an activity is then used.

With the previous notations, let ptvar and dbvar be the processing time variable and the duration of breaks variable for an activity. We have dvar = ptvar + dbvar. Let db be the duration of the breaks in the bucket bkt. The relaxation of the processing time effectively executed in a bucket is given by:


 pt(act, bkt) =	min(bktdur, dvar, evar - bktmin,

 bktmax - svar) - min(db, dbvar)

If the bucket contains the activity execution, then dbvar < db and pt(act, bkt) is reduced to dvar - dbvar = ptvar, and the required energy is ptvar*cvar. If the activity execution overlaps the time bucket, then pt(act, bkt) = bktdur - db = bktmax - bktmin - db, and the required energy is (bktmax - bktmin - db)*cvar, and this is the expected result from the energy with breaks relaxation.

Notice that in case of a non-breakable activity, dbvar = 0 and we have the regular formula for the energy calculation. In the same way, this relaxation allows us to take into account that activities can overlap breaks. Similarly, if no break overlap happens, and if the duration of breaks is equal to the length of the bucket, pt(act, bkt) = 0.

The duration of breaks in a time bucket must be given before the propagation. Otherwise one can always suppose that the time bucket can be filled by breaks, making the relaxation inefficient.

This relaxation may or may not be used in conjunction with break constraints. In the last case, the user must bound the duration of the breakable activities.

The propagation of energy constraints is always based on timetables.

Printing or DisplayingDiscrete Energy Resources

The printed representation of an instance of the class IlcDiscreteEnergy consists of its name, followed by information about its capacity and the time step of its timetable enclosed in parentheses. If no timetable has been created, the empty parenthesis are displayed. For example:

[10 (5)] represents a discrete energy resource with a capacity equal to 10 and a timetable time step equal to 5.

[3 ()] represents a discrete energy resource with a capacity equal to 3 and no timetable.

If the Solver trace is active and the resource is not named, the string "IlcDiscreteEnergy" is followed by the address of the implementation object. The address will be enclosed in parentheses.

For more information, see Calendars, Timetable, Transition Time in Scheduler Engine, and Type Timetable Constraint.

This constructor creates an instance which is empty, that is, one whose handle pointer is null. You must assign it a value before you access it. Any attempt to access it before assignment leads to undefined behaviour.

This constructor creates an instance of the handle class from the pointer to an instance of the implementation class.

Constructor Summary
`public`	`IlcDiscreteEnergy()`
`public`	`IlcDiscreteEnergy(IlcDiscreteEnergyI * impl)`
`public`	`IlcDiscreteEnergy(IlcSchedule schedule, IlcInt timeStep, IlcInt energy, IlcBool timetable=IlcTrue)`
`public`	`IlcDiscreteEnergy(IlcSchedule schedule, IlcInt timeStep, IlcInt energy, IlcTransitionTimeObject ttobj, IlcBool timetable=IlcTrue)`

Method Summary
`public IlcBool`	`areBreaksClosed() const`
`public void`	`closeBreaks()`
`public IlcInt`	`getBreaksDuration(IlcInt time) const`
`public IlcInt`	`getEnergy() const`
`public IlcInt`	`getEnergyMax(IlcInt time) const`
`public IlcInt`	`getEnergyMaxMax(IlcInt timeMin, IlcInt timeMax) const`
`public IlcInt`	`getEnergyMaxMin(IlcInt timeMin, IlcInt timeMax) const`
`public IlcInt`	`getEnergyMin(IlcInt time) const`
`public IlcInt`	`getEnergyMinMax(IlcInt timeMin, IlcInt timeMax) const`
`public IlcInt`	`getEnergyMinMin(IlcInt timeMin, IlcInt timeMax) const`
`public IlcDiscreteEnergyI *`	`getImpl() const`
`public IlcConstraint`	`getTypeTimetableConstraint() const`
`public IlcBool`	`hasTypeTimetableConstraint() const`
`public IlcConstraint`	`makeTimetableConstraintWB(IlcInt timeMin, IlcInt timeMax, IlcInt timeStep, IlcInt energy, IlcInt db)`
`public IlcConstraint`	`makeTypeTimetableConstraint(IlcBool useBatch=IlcFalse)`
`public void`	`operator=(const IlcDiscreteEnergy & h)`
`public void`	`setBreaksDuration(IlcInt timeMin, IlcInt timeMax, IlcInt value)`
`public void`	`setEnergyMax(IlcInt timeMin, IlcInt timeMax, IlcInt energyMax)`
`public void`	`setEnergyMin(IlcInt timeMin, IlcInt timeMax, IlcInt energyMin)`
`public void`	`setTimetablePropagation(IlcInt level=1L)`

Inherited Methods from `IlcCapResource`
`getImpl, getMaxTextureMeasurement, getMinTextureMeasurement, getTimetable, getTimetable, hasInitialOccupation, hasMaxTextureMeasurement, hasMinTextureMeasurement, incrDurableRequirement, incrDurableRequirement, isRedundantResource, makeBalanceConstraint, makeMaxTextureMeasurement, makeMinTextureMeasurement, makeTimetableConstraint, makeTimetableConstraint, makeTimetableConstraint, operator=, setInitialOccupation, setInitialOccupation, unsetInitialOccupation`

Inherited Methods from `IlcResource`
close, getCalendar, getDisjunctiveConstraint, getDurableSchedule, getImpl, getLastRankedFirstRC, getLastRankedLastRC, getLastSurelyContributingRankedFirstRC, getLastSurelyContributingRankedLastRC, getName, getObject, getOldLastRankedFirstRC, getOldLastRankedLastRC, getPrecedenceGraphConstraint, getSchedule, getSolver, getSolverI, getTimetableConstraint, getTransitionTime, hasCalendar, hasDisjunctiveConstraint, hasLightPrecedenceGraphConstraint, hasPrecedenceGraphConstraint, hasPrecedenceInfo, hasRankInfo, hasTimetableConstraint, isCapacityResource, isClosed, isContinuousReservoir, isDiscreteEnergy, isDiscreteResource, isDurable, isReservoir, isStateResource, isTransitionTimeSuspended, isUnaryResource, makeFunctionalConstraint, makeIntegralConstraint, makeLightPrecedenceGraphConstraint, makePrecedenceGraphConstraint, operator!=, operator=, operator==, setCalendar, setName, setObject, setTransitionTimeObject, setTransitionTimeSuspended, whenContribution, whenDirectPredecessors, whenDirectSuccessors, whenNext, whenPossibleNext, whenPossiblePrevious, whenPredecessors, whenPrevious, whenRankedFirstRC, whenRankedLastRC, whenSuccessors

This constructor creates a new instance of IlcDiscreteEnergy and adds it to the set of resources managed in the given schedule. If timetable is IlcTrue, then a timetable constraint is posted; that constraint states that the energy of the resource is limited to energy for each interval [t (t + timeStep)) where t = timeMin + i * timeStep, timeMin is the origin, and t is less than the horizon.

An instance of IloSolver::SolverErrorException is thrown if any of the following conditions occur:

if timeStep is not strictly positive;
if the time horizon minus the time origin is not a multiple of timeStep;
if energy is negative.

If timetable is IlcFalse, then energy is managed as the energy of the resource, and timeStep is ignored in that case.

This constructor creates a new instance of IlcDiscreteEnergy and adds it to the set of resources managed in the given schedule. If timetable is IlcTrue, then a timetable constraint is posted; that constraint states that the energy of the resource is limited to energy for each interval [t (t + timeStep)) where t = timeMin + i * timeStep, timeMin is the origin, and t is less than the horizon.

An instance of IloSolver::SolverErrorException is thrown if any of the following conditions occur:

if timeStep is not strictly positive;
if the time horizon minus the time origin is not a multiple of timeStep;
if energy is negative.

If timetable is IlcFalse, then energy is managed as the energy of the resource, and timeStep is ignored in that case.

The argument ttobj indicates which transition time function will be used for the invoking resource. The argument ttobj must have been built with an instance of IlcTransitionTable. Transition times are taken into account only when the type timetable constraint is posted. Please see Transition Time in Scheduler Engine and Type Timetable Constraint for more information.

This member function returns IlcTrue if all the timetables with breaks declared on the invoking energy resource are closed. If a timetable with breaks is closed, the durations of breaks is completely specified for each bucket of the timetable.

At post time of the timetable constraints, the declaration of the break duration is automatically closed.

This member function closes the declaration of the duration of breaks for all the timetables with breaks declared on the invoking energy. If a timetable with breaks is closed, the durations of breaks is completely specified for each bucket of the timetable.

At post time of the timetable constraints, the declaration of the break duration is automatically closed.

This member function returns the duration of breaks declared in the bucket of the timetable containing the given time. If the timetable does not take into account the duration of the breaks per bucket, it returns 0. An instance of IloSolver::SolverErrorException is thrown if the timetables of the invoking resource do not cover the given time.

This member function returns the theoretical energy of the invoking resource, that is, the energy that was passed to the resource constructor. If the theoretical energy is unlimited, this member function returns IlcIntMax.

This member function returns the maximal energy that can be used at the given time. An instance of IloSolver::SolverErrorException is thrown if a timetable of the invoking resource do not cover the given time.

This member function returns the maximal energy that can be used throughout the interval [timeMin, timeMax) (that is, the maximal value over the interval [timeMin, timeMax) of the maximal resource energy). An instance of IloSolver::SolverErrorException is thrown if the timetables of the invoking resource do not cover the complete interval indicated by [timeMin, timeMax).

This member function returns the maximal value, over the interval [timeMin, timeMax), of the minimal resource energy. An instance of IloSolver::SolverErrorException is thrown if the timetables of the invoking resource do not cover the complete interval indicated by [timeMin, timeMax).

This member function returns the minimal energy that must be used at the given time. An instance of IloSolver::SolverErrorException is thrown if the timetables of the invoking resource do not cover the given time.

This member function returns the minimal value, over the interval [timeMin, timeMax), of the maximal resource energy. An instance of IloSolver::SolverErrorException is thrown if the timetables of the invoking resource do not cover the complete interval indicated by [timeMin, timeMax).

This member function returns the minimal energy that must be used throughout the interval [timeMin, timeMax) (that is, the minimal value over the interval [timeMin, timeMax) of the minimal resource energy). An instance of IloSolver::SolverErrorException is thrown if the timetables of the invoking resource do not cover the complete interval indicated by [timeMin, timeMax).

This member function returns a pointer to the implementation object of the invoking handle.

This member function returns the type timetable constraint of the invoking resource.

This member function returns IlcTrue if the invoking resource has a type timetable constraint. Otherwise, it returns IlcFalse.

This member function creates and returns a timetable constraint taking into account both the energy and the duration of breaks per buckets for the invoking resource. This timetable constraint implies that the energy per bucket of the resource is limited to energy, and the duration of breaks per bucket is limited to db. The constraint is enforced from timeMin to timeMax and allows to change the energy and duration of breaks per buckets only at times timeMin + i*timeStep.

An instance of IloSolver::SolverErrorException is thrown if any of the following conditions occur:

if timeStep is not strictly positive;
if timeMin is not strictly less than timeMax;
if timeMax minus timeMin is not a multiple of timeStep;
if the new timetable overlaps another timetable that has already been created for the invoking resource.

This member function attaches a type timetable constraint to the resource and returns it.

The type timetable constraint uses the transition time object that was passed to the constructor of the invoking resource to propagate the transition times. This transition time object needs to have been built with an instance of IlcTransitionTable. An instance of IloSolver::SolverErrorException is thrown if no transition time object was passed to the constructor of the resource or if the transition time object was not built with an instance of IlcTransitionTable.

The useBatch parameter allows you to batch overlapping activities together that use the same resource and that are of the same transition type. Basically, if the execution time of the activities overlaps on the resource, then the activities will be constrained to start and end at the same time. If the execution time of the activities does not intersect on the resource, then the useBatch parameter has no effect on the activities. Although the activities must be of the same transition type, the transition time has no effect on the action of useBatch.

This operator assigns an address to the handle pointer of the invoking object. That address is the location of the implementation object of the provided argument. After execution of this operator, the invoking object and the provided argument point to the same implementation object.

This member function returns the duration of breaks in the buckets that intersect the interval [timeMin, timeMax). If the timetable has its declaration of the duration of breaks closed, the call to the function is ignored. An instance of IloSolver::SolverErrorException is thrown if the timetables of the invoking resource do not cover the complete interval indicated by [timeMin, timeMax).

This member function states that at most energyMax can be used throughout at the interval [timeMin, timeMax). An instance of IloSolver::SolverErrorException is thrown if the timetables of the invoking resource do not cover the complete interval indicated by [timeMin, timeMax).

This member function states that at least energyMin must be used throughout at the interval [timeMin, timeMax). An instance of IloSolver::SolverErrorException is thrown if the timetables of the invoking resource do not cover the complete interval indicated by [timeMin, timeMax).

The resource must be closed in order to propagate a non-zero minimal energy.

When the argument level is equal to 1, this member function switches on extra propagation for the maximal duration and maximal capacity of resource constraints on the resource. This extra propagation globally analyzes the timetable of the resource to identify two things:

Temporal intervals where the maximal duration of the activity can be supported if the resource constraint requires its minimal capacity
Temporal intervals where the maximal capacity of the resource constraint can be supported if the duration of the activity equals its minimal duration.

The constraint finds new upper bounds on duration and capacity that are supported by such time intervals.

For example, consider a schedule with 3 activities: a0 (fixed start time 0, fixed end time 8), a1 (fixed start time 15, fixed end time 20) and a2 (earliest start time 0, latest end time 21, variable duration in [13..21]). All three activities require the same discrete energy resource res (time step = 7, energy = 100 on each steps [0..7),[7..14),[14..21) etc.). Suppose that a0 and a1 both require 10 units of res. The extra propagation at level 1 will deduce that, given the current timetable, the maximal capacity of a2 is 12, and that this maximal capacity can be satisfied if a2 starts at 5 and finishes at 18.

When the level is equal to 0, the extra propagation above is not performed. The propagation level can be changed in a reversible way during the search.

Class IlcDiscreteEnergy