Path Annotation Script

Relates to versions - 1.6.8

Introduction

READ THE GIANT WARNINGS

The equipment path annotation script allows users who are using the source scheduling component of
Spry to inline basic constraints, dependency directives as well as some controls for path rewriting.
While similar outcomes can be achieved using the existing Dependencies and Constraints section,
this functionality assists in streamlining source scheduling. This is particularly useful in short-term
scenarios where equipment interactions are a major concern and frequent rescheduling takes place.
The constructs are implemented as a series of special comments that are attached to specific source
path lines. For example:

Strip/1/2/12-8/C/60-50 'waitfree delay=3days

In a more general form, this is:

<annotated task> ' !<directive> <argument>

The annotation script can then be configured to recognize these directives (normally, they are
comments which are ignored by Spry) and add additional behaviours to them. By convention, the
comments are intended to affect behaviour related to the annotated tasks.

GIANT WARNINGS

Use of this script is intended for competent users only and is not officially supported. It represents a prototyping framework to test and receive feedback for proposed future features in Spry source paths.

 

There is no guarantee that the capabilities implemented herein will eventually be incorporated into - or even remain compatible with - future versions of Spry or even the script itself. As with anything, this is to be used at your own risk.

 

When the behaviour of this script is used in conjunction with stockpiles has not been tested and is effectively undefined. As this is still undergoing testing, there is a high chance that breaking changes will occur. More so than normal, use at your own risk.

 

The functionality described herein is not a default of Spry functionality. This functionality added via the use of a script that hooks into the schedule run. Please do not expect this to work in all Spry models. It is necessary to read this document and then apply critical assessment.

 

Try to avoid using Allow Advance with the path annotation script. One of the major motivations in the creation of this script was to obviate the need for Allow Advance.

Installation

This script can be downloaded from the attachments tab.

Add the attached script to the Spry scripting area, and then in the Case Settings, to invole the script on scheduling setup:

Note that if you already have an existing setup script, you can add a line to the script to invoke the path annotator:

For convenience, you can copy and past the appropriate code into your scripts below:

 

public class ExistingSetupScript
{
public static void Setup(SchedulingEngine se)
{
// existing logic here
// ..

EquipmentPathAnnotation.SetupEngine(se);
}
}

For any equipment you with you use the path annotation syntax for, you must explicitly enable the path annotation by adding this line to the top of the file (or at least before any other annotation commands)

 

'!equipmentpathannotation_enable This uses the equipment path annotation script. It is an unsupported utility with some documentation provided on the micromine help site

Annotation Commands

The following annotation directives are supported:

!waitfree

Suppress processing of the annotated tasks until they all free of external predecessors (the term external is explained below). Semantically, this has the effect of grouping the annotated tasks and processing them only when they are all free of external predecessors. This is implemented as a constraint and hence is specific to the equipment only (as opposed to !dependfree ), at the cost of greater performance.

Here, 'external' refers to predecessors that are not part of the annotated tasks themselves. To provide an intuitive explanation of why this is done, consider the following path:

Strip/1/2/12-8/60-50 ' !waitfree

This line contains multiple benches. If there is a top-down dependency in place, it is likely that the tasks at RL 50 have a dependency to wait on the tasks at RL 60. It is not constructive for these dependencies to be included in the wait, as they effectively set a circular dependency (strictly speaking not dependency per se) and hence they are excluded.

!waitfree examples

 

Example	Description
Strip/1/2/12-8/C/60 '!waitfree
Strip/1/2/12-8/C/60 '!waitfree delay=3days	Once the tasks are free, delay an additional 3 days. This may be useful for modelling cleanup activities.

 

Note that waitfree, while powerful, often leads to confusion when it is misused. Some additional notes about troubleshooting this are discussed in the troubleshooting section below

 

!waiton

Prevent processing of all tasks until all of the specified tasks in the argument have been completed.

This is implemented as a constraint and hence is specific to the equipment only (as opposed to !dependon ), at the cost of greater performance.

!waiton examples

 

Example	Description
Strip/1/2/12-8/C/60 ' !waiton Strip/1/1/12-8/C <coal>
Strip/1/2/12-8/C/60 ' !waiton s:Strip/1/1/12-8/C <coal>	Explicitly indicate the predecessor tasks are source tasks
Strip/1/2/12-8/C/60 ' !waiton d:dump1/1/1/14	Explicitly indicate the predecessor tasks are destination tasks
Strip/1/2/12-8/C/60 ' !waiton Strip/1/1/12-8/C <coal> delay=1day	Once predecessor tasks are complete, delay for an additional day
Strip/1/2/12-8/C/60 ' !waiton s:Strip/1/1/12-8/C <coal> delay=4hours	Combination of above
Strip/1/2/12-8/C/60 ' !waiton d:dump1/1/1/14 delay=30min	Combination of above

Note that waiton, while powerful, often leads to confusion when it is misused. Some additional
notes about troubleshooting this are discussed in the troubleshooting section below

!dependfree

Set dependency so all annotated tasks in path will wait on all predecessors of annotated tasks in path.
This is effectively a cross-dependency - for N annotated tasks with a total of M dependencies across
them, the number of dependencies set will be N x M. It is implemented as a dependency and hence the restriction will apply to all equipment and will perform faster than !waitfree .

!dependfree examples

 

Example	Description
Strip/1/2/12-8/C/60 '!dependfree
Strip/1/2/12-8/C/60 '!dependfree delay=3day	Once the tasks are free, delay an additional 3 days. This may be useful for modelling cleanup activities.

!dependon

Set dependency so all annotated tasks in path will wait on all predecessors of annotated tasks in path.
This is effectively a cross-dependency - for N annotated tasks with a total of M dependencies across them, the number of dependencies set will be N x M. It is implemented as a dependency and hence the restriction will apply to all equipment and will perform faster than !waiton

!dependon examples

 

Example	Description
Strip/1/2/12-8/C/60 ' !dependon Strip/1/1/12-8/C <coal>
Strip/1/2/12-8/C/60 ' !dependon s:Strip/1/1/12-8/C <coal>	Explicitly indicate the predecessor tasks are source tasks
Strip/1/2/12-8/C/60 ' !dependon d:dump1/1/1/14	Explicitly indicate the predecessor tasks are destination tasks
Strip/1/2/12-8/C/60 ' !dependon Strip/1/1/12-8/C <coal> delay=1day	Once predecessor tasks are complete, delay for an additional day
Strip/1/2/12-8/C/60 ' !dependon s:Strip/1/1/12-8/C <coal> delay=4hours	Combination of above
Strip/1/2/12-8/C/60 ' !dependon d:dump1/1/1/14 delay=30min	Combination of above

!dependclear

Clear annotated tasks of predecessors.

Arguments can be applied to limit the time of application and predecessors cleared.

 

Note: this feature was originally implemented before the Ignore Dependencies
directive was implemented in source paths. It is left in for legacy reasons but it is worth considering if the directive may be more applicable

!dependclear examples

 

Example	Description
Strip/1/2/12-8/C/60 ' !dependclear	Immediately clear all predecessors from annotated tasks
Strip/1/2/12-8/C/60 ' !dependclear A/1/2 <asdf>	Immediately clear predecessor tasks in the range A/1/2 from annotated tasks
Strip/1/2/12-8/C/60 ' !dependclear on=1/1/2016	Clear all predecessors from annotated tasks on 1/1/2016
Strip/1/2/12-8/C/60 ' !dependclear A/1/2 <asdf> on=4 April 2015	Combination of above

!remove

Remove the annotated line from the equipment source path based on a variety of triggers.

 

This is intended to be used with the Allow Duplicates: On directive. Without this directive, subsequent path lines intended to process the same tasks are removed by the Scheduling Engine (for optimisation/performance reasons), so removal of the path would permanently prevent the equipment from processing removed tasks. This behaviour may or may not be desired.

This removes only the annotated line from the equipment source path. If Allow Duplicates is enabled it is possible that tasks in the annotated line still exist elsewhere in the equipment source path.

!remove examples

 

Example	Description
Strip/1/2/12-8/C/60 ' !remove	Immediately remove this line from the equipment path
Strip/1/2/12-8/C/60 ' !remove tasks=A/1/2 <asdf> event=available	Remove this line from the equipment path when the tasks A/1/2 become available (free of dependencies)
Strip/1/2/12-8/C/60 ' !remove tasks=A/1/2 <asdf> event=completed	Remove this line from the equipment path when the tasks A/1/2 have been completed
Strip/1/2/12-8/C/60 ' !remove tasks=A/1/2 <asdf> event=completed delay=12h	Remove this line from the equipment path 12 hours after the tasks A/1/2 have been completed
Strip/1/2/12-8/C/60 ' !remove tasks=A/1/2 <asdf> event=available delay=12h	Remove this line from the equipment path 12 hours after the tasks A/1/2 become available (free of dependencies)
Strip/1/2/12-8/C/60 ' !remove on=1/1/2016	Remove this line from the equipment path on the 1/1/2016

 

!timeconstrain

Prevent processing of annotated tasks based on hard time limits. This can be used to either allow
activity within the specific limits, or suppress activity within the specific limits.

!timeconstraint examples

 

Example	Description
Strip/1/2/12-8/C/60 ' !timeconstrain	Prevent processing of annotated tasks from the start to end of the schedule
Strip/1/2/12-8/C/60 ' !timeconstrain mode=suppress start=1/1/2016 end=1/2/2016	Prevent processing of annotated tasks between 1/1/2016 and 1/2/2016
Strip/1/2/12-8/C/60 ' !timeconstrain mode=allow start=1/1/2016 end=1/2/2016	Allow processing of annotated tasks only between 1/1/2016 and 1/2/2016
Strip/1/2/12-8/C/60 ' !timeconstrain mode=allow start=1/1/2016	Allow processing of annotated tasks only after 1/1/2016
Strip/1/2/12-8/C/60 ' !timeconstrain mode=suppress end=1/1/2016	Prevent processing of annotated tasks until 1/1/2016

 

!deadhead / !delayafter

Apply a delay after the annotated tasks have been completed

 

This delay occurs even if the tasks are completed by other equipment.

!deadhead examples

 

Example	Description
Strip/1/2/12-8/C/60 ' !deadhead 12h	Delay for 12 hours after the annotated tasks have been completed. The equipment's nonproductive process will be used for the delay
Strip/1/2/12-8/C/60 ' !deadhead 16h process=Deadheading	Delay for 16 hours after the annotated tasks have been completed. The nonproductive process 'deadheading' will be used for the delay

 

!forcecompletion

Force the line to complete at a specific date.

 

T he completion is achieved by setting the source rate to a sufficiently high value to
complete instantaneously. T his will have implications for any trucking calculations.complete instantaneously. T his will have implications for any trucking calculations

!forcecompletion examples

 

Example	Description
Strip/1/2/12-8/C/60 ' !forcecompletion	Force the tasks to instantaneously complete at the start of the schedule
Strip/1/2/12-8/C/60 ' !forcecompletion on=1/1/2017	Force the tasks to be instantaneously completed on the 1st January 2017
Strip/1/2/12-8/C/60 ' !forcecompletion on=1/1/2017 obey=all	Attempt to force the tasks to be instantaneously completed on the 1st January 2017. However, still honour any dependencies and/or constraints
Strip/1/2/12-8/C/60 ' !forcecompletion on=1/1/2017 obey=dep	Attempt to force the tasks to be instantaneously completed on the 1st January 2017. However, still honour any dependencies
Strip/1/2/12-8/C/60 ' !forcecompletion on=1/1/2017 obey=con	Attempt to force the tasks to be instantaneously completed on the 1st January 2017. However, still honour any constraints

!reprioritise

When the equipment acquires any of the tasks on this line, these tasks will be moved to the top of the
equipment path list. This has the effect of reprioritising them, hence the name.

This is generally only meaningful with use of Allow Advance: On , as it is only with this directive that
the equipment can 'advance' past tasks.

The envisioned usage here is basically to allow equipment to advance past previous tasks, but then
'lock on' to these tasks (i.e. it will attempt to finish what it starts).

The existence of this feature should not be taken as endorsement to use it. Allow Advance: On is
generally not recommended with this script. However the implementation was done as part of the
never ending arms race between bad practice and the features designed to mitigate the negative
outcomes of such bad practice.

!injectschedulepath

TODO

Inject a schedule path from another scenario.

This may be useful when trying to frankenstein cases together. It should be noted that it simply
converts an existing schedule steps from another schedule into an input path for this case. As an input
path is an attempt to schedule, there is no guarantee that it actually will for any number of reasons
(dependencies, constraints, mismatching volumes, preschedule, prefilter, already processed etc)

In general, it is expected that the source Case closely matches the Case that this is implemented in
(with regards to processes, preschedule, reserves etc).

The order of this command relative to other path elements is (or should be) honoured.

!injectschedulepath examples

 

Example	Description
' !injectschedulepath case=Other Case	Copy output schedule from case named other case, for the equipment with the same full path name as this equipment. Ignore all dependencies and constraints.
' !injectschedulepath case=Other Case start=1/1/2018 end=1/6/2018	Copy output schedule only for period from 1/1/2018 to 1/6/2018
' !injectschedulepath case=Other Case type=input	Copy input schedule from case named other case
' !injectschedulepath case=Other Case equipment=Excavators/EX1000	Same as first example but path from equipment named Excavators/EX1000
' !injectschedulepath case=Other Case obey=all	Honour dependencies and constraints
' !injectschedulepath case=Other Case obey=dep	Honour Dependencies
' !injectschedulepath case=Other Case obey=con	Honour Constraints

 

Argument Formatting

Some types of arguments are common amongst the different directives. This section discusses the
appropriate formatting options available to them.

Delay Formats

Various directives allow for a delay= argument to be applied. This argument specifies a delay period
between the event trigger time and when an item is released. In essence, the format is [number][unit
specifier], where number is a numeric value and the unit specifier is m , h , d or w for minute, hour,
day or week respectively.

 

 

Examples	Description
20m	20 Minutes
2.5h	2.5 Hours
1d	1 Day
2.25w	2.25 Weeks

Source \ Destination Formats

Some directives can take a subset of tasks as an argument. As tasks can be either source tasks or
destination tasks, the s: or d: prefix can be used to explicitly specify what type of tasks where
applicable. Without this prefix, it will default assuming the argument relates to source tasks.

Source \ Destination Format Examples

 

 

Examples	Description
s:A/1/1	Source Tasks
d:A/1/1	Destination Tasks
A/1/1	Source Tasks; because no prefix is specified, source tasks are assumed

 

Dates

Various directives allow for a on= , start= , end= argument to be applied. This argument specifies a
date at which a particular event should occur.

Internally, the script calls the C# method System.DateTime.Parse, so theoretically any string accepted
by that method should be valid.

 

The behaviour of this parse method also depends on the region/locale settings of the host Operating System. Different locales can produce different results for the same literal string. For instance, the string 1/12/2016 will represent the date 1st December 2016 in an Australian locale. In a US locale, this will represent the date 12 January 2016

Date Examples

 

Examples	Description
1/1/2020	1/1/2020 12:00 AM (Midnight)
5/7/2020 2:37 PM	5/7/2020 2:37 PM
5/7/2020 2:37 AM	5/7/2020 2:37 AM
5/7/2020 2:37	5/7/2020 2:37 AM
5/7/2020 14:37	5/7/2020 2:37 PM

Snapshot Troubleshooting

The path annotation directives provide substantial power in more expressive scheduling, but this
comes concomitant complexity that can be difficult to troubleshoot. Some integration with the schedule
snapshot tool is provided to assist with this.

Dependencies

For !depend directives, the dependency will describe the relevant Equipment Source Path Line
where the dependency was set:

Wait Constraints

For !wait directives, the snapshot viewer will explain the relevant Equipment Source Path line where
the constraint was set. This can come in three forms:

• A wait is currently in effect. Here the drill task is waiting on 5 tasks which have not yet
  completed due to a directive set on line 3 of the drill's source path.

• A wait is currently in effect. Here the drill task is still constrained because it has been subject to
  a release delay. The tasks it was previously waiting on have been completed, but a delay has
  been specified (in this case 1 day) and the tasks will be constrained until 1 day after the
  completion.

• No wait is being applied. The drill task was previously waiting on 5 tasks, but these have been
  completed. This information is provided for debugging purposes.

Want to learn more?

Click here to login to our Learning Management System

Click here to request access