OptimizationMgr (CPIK Libraries)

Contents

Overview

A class representing the Advanced Optimization module within CoPilot.
Android Support
>=9.6.0.821
iOS Support
>=10.9
Type
Class
Package
com.alk.cpik.optimization

Constructors

Methods

Method Name Return Type Description
start()
OptStatus
Starts the Optimization process for given stops.
stop()
Boolean
Stops the optimization process.

Hooks and Callbacks

Hooks and Callbacks related to Optimization can be found below.

OptimizationListener

  • onOptimizationProgress
  • onOptError
  • onOptStopError
  • onOptStopGeocode
  • onOptResult

OptimizationMgr.start

Overview

Starts the optimization process for given stops
Android Support
>=9.6.0.821
iOS Support
>=9.6.0.821
Linux Support
>=9.6.0.821
Type
Class
Package
com.alk.cpik.optimization

Syntax

Parameters

optInHeader - An object containing header information. lstOptStop - List of the input stops and break stops sending for optimization.

Return Value

Returns an OptimizationStatus detailing the result of the optimization.

Sample Code

// We are using dummy OptimizationInHeader values and OptimizationInStop values.
// for further details please refer to the CPIK sample App.
OptimizationInHeader optInHeader = new OptimizationInHeader();
ArrayList<OptimizationInStop> lstOptStop = new ArrayList<OptimizationInStop>();

double latitude = 55.837394;
double longitude = -4.062002;
optInHeader.setStartStopLatLon(new Coordinate(latitude, longitude));

latitude = 55.827200;
longitude = -4.065468;
optInHeader.setEndStopLatLon(new Coordinate(latitude, longitude));
OptimizationInStop optInStop = new OptimizationInStop();
latitude = 55.827202;
longitude = -4.065467;
optInStop.setStopNumber((short)1);
optInStop.setCoordinate(latitude, longitude);
lstOptStop.add(optInStop);

latitude = 55.827301;
longitude = -4.065568;
optInStop.setStopNumber((short)2);
optInStop.setCoordinate(latitude, longitude);
lstOptStop.add(optInStop);

boolean bETAOnly = false;
optInHeader.setIsETACalculation(bETAOnly);

OptimizationEnums.OptimizationStatus optStatus = OptimizationMgr.start(optInHeader, lstOptStop);

//failed to start, release semaphore to continue to the next file
if (optStatus == OptimizationEnums.OptimizationStatus.SUCCESS)
  System.out.println("Optimization started successfully.");
else {
  String status = "";
  if (optStatus == OptimizationEnums.OptimizationStatus.FAILED_OPT_ALREADY_RUNNING)
    status = "Optimization Already Running";
  else if (optStatus == OptimizationEnums.OptimizationStatus.FAILED_OPT_UNLICENSED)
    status = "Optimization feature is not licensed in CoPilot";
  else if (optStatus == OptimizationEnums.OptimizationStatus.FAILED_GENERAL_ERROR)
    status = "Optimization did not start due to unknown error.";
  else
    status = "Optimization did not start due to unknown error.";
  Log.v("Optimization", status);
  System.out.println(status);

}

Hooks and Callbacks

Hooks and Callbacks related to Optimization can be found below.

OptimizationListener

  • onOptimizationProgress
  • onOptError
  • onOptStopError
  • onOptStopGeocode
  • onOptResult

Related APIs

  • Optimization.start()
  • Optimization.stop()

OptimizationMgr.stop

Stops the optimization process.
Android Support
>=9.6.0.821
Linux Support
>=9.6.0.821
Type
Method
Package
com.alk.cpik.optimization
Overview
Description Stops the optimization process.
Supported Since Version 9.6.0.821
Platforms Supported Android, Linux
Type Method
Package com.alk.cpik.optimization

Syntax

Return Value

Returns true to indicate that a request is being made for optimization to stop.

Returns false to indicate that optimization is already stopped.

Sample Code

String status = "";
if (OptimizationMgr.stop())
  status = "Stop Optimization is processing by optimization engine";
else
  status = "Stop Optimization failed";

Log.v("Optimization", status);
System.out.println(status);

Hooks and Callbacks

Hooks and Callbacks related to Optimization can be found below.

OptimizationListener

  • onOptimizationProgress
  • onOptError
  • onOptStopError
  • onOptStopGeocode
  • onOptResult

OptimizationStatus

An enum of responses from a request for optimization.
Android Support
>=9.6.0.821
Type
Enum
Package
com.alk.cpik.optimization

Values

Value Description
SUCCESS Request to optimization is successful.
FAILED_OPT_ALREADY_RUNNING Optimization is already running. Cannot initiate second instance of the optimization.
FAILED_OPT_UNLICENSED Optimization feature is not licensed in CoPilot.
FAILED_GENERAL_ERROR Optimization request failed due to unknown error.

Hooks and Callbacks

Hooks and Callbacks related to Optimization can be found below.

OptimizationListener
onOptimizationProgress
onOptimizationError
onOptimizationStopError
onOptimizationStopGeocode
onOptimizationResult

OptimizationNotification

Overview
Description This is being sent by the optimization engine to the CPIK application to provide optimization progress.
Supported on Android Since Version 9.6.0.821
Type Enum
Package com.alk.cpik.optimization

Values

Value Description
OPT_GEOCODE_STARTED Optimization engine started geocoding of the stops.
OPT_GEOCODE_FINISHED Optimization engine finished geocoding of the stops.
OPT_DELIVERY_24HOURS Delivery time for all the stops are more than 24 hours.

Hooks and Callbacks

Hooks and Callbacks related to Optimization can be found below.

OptimizationListener

  • onOptimizationProgress
  • onOptError
  • onOptStopError
  • onOptStopGeocode
  • onOptResult

OptimizationError

Overview
Description This is being sent by the optimization engine when encountering an error with the optimization process. Optimization will stop after receiving any of these errors.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Enum
Package com.alk.cpik.optimization

Values

Value Description
OPT_NONGEOCODABLE_HEADER_STOPS Start/End stop cannot be geocoded. It means either it is wrong latitude/longitude, wrong format or outside of the CoPilot map region.
OPT_TIMEOUT Optimization timed out before optimization finished.
OPT_CANCEL Optimization is stopped by calling Optimization.stop() method before optimization finished.

Hooks and Callbacks

Hooks and Callbacks related to Optimization can be found below.

OptimizationListener
onOptimizationProgress
onOptimizationError
onOptimizationStopError
onOptimizationStopGeocode
onOptimizationResult

OptimizationStopError

Overview
Description This is being sent by the optimization engine when encountering an error with an individual stop. Optimization will still continue after sending the stop error.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Enum
Package com.alk.cpik.optimization

Values

Value Description
ERROR_MAXDISTANCE Stop is more than 100 miles away from route. This stop will be removed from the optimization list. “Max Distance” configuration: By default CoPilot sets the max distance as 100 miles, which is measured as a matrix of all stops to identify any that are potentially incorrect locations. This means that if a destination is over 100 miles away from all other stops, it will be removed from the optimization. To change the default value add the following section to the user.cfg file
[Optimization]
“MaxAirTravelMile”=100
ERROR_DELIVERY_MIDNIGHT Delivery time for the given stop is passing through midnight.
ERROR_TIME_WINDOW Stop’s end time is earlier than its own start time or the start time of the trip.
ERROR_WAIT_TIME Wait time for a regular stop is more than 30 minutes or wait time for a break stop is more than 2 hours.
ERROR_BREAK_INSERT Stop was marked as a break stop but could not be inserted into the end sequence. Common reasons for this error include setting a break time outside of the driver’s working hours or setting a final break time after the final stop has been completed.

Hooks and Callbacks

Hooks and Callbacks related to Optimization can be found below.

OptimizationListener
onOptimizationProgress
onOptimizationError
onOptimizationStopError
onOptimizationStopGeocode
onOptimizationResult

OptimizationDeliveryType

Overview
Description Type of optimization delivery whether single time window, dual time window or single time window with block time.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Enum
Package com.alk.cpik.optimization

Values

Value Description
OPT_WITH_SINGLE_TIMEWINDOW Stop having single time window…Second time window parameter will be ignored.
OPT_WITH_DUAL_TIMEWINDOW Stop having dual time window. OptInStop.mOpt2ndTimeOrBlockWindowStart and OptInStop.mOpt2ndTimeOrBlockWindowEnd contain the second time window.
OPT_WITH_BLOCKTIMEWINDOW Stop having single time window with block time window. OptInStop.mOpt2ndTimeOrBlockWindowStart and OptInStop.mOpt2ndTimeOrBlockWindowEnd contain the block time window.

Hooks and Callbacks

Hooks and Callbacks related to Optimization can be found below.

OptimizationListener
onOptimizationProgress
onOptimizationError
onOptimizationStopError
onOptimizationStopGeocode
onOptimizationResult

OptimizationInHeader

Overview
Description Optimization/ETA calculation header information including start time, starting position, ending position and a time out duration.

Within the input file, Stop number 1 should be passed as the first stop and an increment of 1 for each subsequent stop should be passed to ensure consistent output results are received.

Supported on Android Since Version 9.6.0.821
Type Class
Package com.alk.cpik.optimization

Public Constructors

Constructor Name Description
OptimizationInHeader() A default constructor of OptimizationInHeader.
OptimizationInHeader(short, Coordinate, Coordinate, boolean, short, OptimizationDeliveryType) A overloading constructor of OptimizationInHeader with params.

Members

Member Name Return Type Description
mStartTime
Short
Start Time of the Trip (Minutes starting from midnight E.g 07.00AM can be represented 60* 7 = 420, 14.30pm can be represented using 60*14 + 30 = 870)
mStartStopLatLon
Coordinate
Lat/Lon of the starting stop from where route will be started, typically it will be a depot.
mEndStopLatLon
Coordinate
Lat/Lon of the ending stop from where route will be end, typically it will be a depot.
mIsETACalculation
boolean
Whether it is ETA calculation or Optimization… True: It will only do ETA calculation False: It will do optimization
mTimeout
Short
Timeout in seconds. Will timeout if the route calculation has not completed within the required period.
mOptDeliveryType
OptimizationDeliveryType
Type of optimization delivery whether single time window, dual time window or single time window with block time

Methods

Method Name Return Type Description
setStartTime(short)
void
Sets the optimization start time.
getStartTime()
Short
Gets the optimization start time.
setStartStopLatLon(Coordinate)
void
Sets start stop using latitude and longitude values.
getStartStopLatLon()
Coordinate
Gets the latitude and longitude values fo start stop.
setEndStopLatLon(Coordinate)
void
Sets end stop using latitude and longitude values.
getEndStopLatLon()
Coordinate
Gets end stop using latitude and longitude values.
setETACalculation(Boolean)
void
Sets ETA calculation.
getETACalculation()
boolean
Gets the ETA calculation.
setTimeout(short)
void
Sets the time out for the optimization process.
getTimeout()
Short
Gets the time out for the optimization process.
setOptDeliveryType(OptEnum.OptDeliveryType)
void
Sets optimization delivery windows type.
getOptDeliveryType() OptimizationEnum.OptDeliveryType This return the delivery windows type.

Hooks and Callbacks

Hooks and Callbacks related to Optimization can be found below.

OptimizationListener
onOptimizationProgress
onOptimizationError
onOptimizationStopError
onOptimizationStopGeocode
onOptimizationResult

OptimizationInStop

Overview
Description Input stop information including stop details, start time, end time, waiting time, optional further start/end time, and optional block time.

Within the input file, Stop number 1 should be passed as the first stop and an increment of 1 for each subsequent stop should be passed to ensure consistent output results are received.

Supported on Android Since Version 9.6.0.821
Type Class
Supported on iOS Since Version 10.9
Package com.alk.cpik.optimization

Public Constructors

Method Name Description
OptimizationInStop() A constructor of OptimizationInStop to create and own Coordinate object

Members

Member Name Return Type Description
mStopNo
Short
Stop sequence number. For a Normal stop, it must be start with 1. Maximum stops supported are 999. Stop sequence number will be unique and help to map when the optimization engine returns the optimization/ETA calculation result. For a Break stop, it must start with 1001. For a Static stop, it must start with 2001. Further details on static stops can be found within the CoPilot Feature Guide.
mStopName
String
Descriptive name for the stop. This will be displayed on stop labels throughout the application.
address
Address
The address portion of a stop. A stop must first be built using StopBuilder and then getAddressObject(). called.
mTimeWindowEnd
Short
End time for time window. (Minutes starting from midnight.)
mOpt2ndTimeOrBlockWindowStart
Short
Start time for second or block time windows (Minutes starting from midnight.) If there is no second time window, then pass 0.
mOpt2ndTimeOrBlockWindowEnd
Short
End time for second or block time window.
mWaitTime
Short
Wait time (Seconds). The wait time is the time the driver will be at the stop completing the required task before continuing driving.
mClusterID
String
Cluster ID can be used to modify the CoPilot clustering logic. It is not recommended that this is used as standard and consultation with ALK on the implementation is recommended. Dependency on configuration options are present.

Methods

Method Name Return Type Description
setStopNumber (short)
void
Sets the stop number.
getStopNumber ()
Short
Gets the stop number.
setTimeWindowStart (short)
void
Sets time window start.
getTimeWindowStart ()
Short
Gets time window start.
setTimeWindowEnd (short)
void
Sets time window End.
getTimeWindowEnd ()
Short
Gets time window End.
Set2ndTimeOrBlockWindowStart (short)
void
Sets 2nd time or block window start .
Get2ndTimeOrBlockWindowStart()
Short
Gets 2nd time or block window start.
Set2ndTimeOrBlockWindowEnd (short)
void
Sets 2nd time or block window End.
Get2ndTimeOrBlockWindowEnd ()
Short
Sets 2nd time or block window End.
setWaitTime (short)
void
Sets wait time.
getWaitTime ()
Short
Gets wait time.
setClusterID(String)
void
Sets cluster ID
getClusterID()
String
Gets Customer ID.

Hooks and Callbacks

Hooks and Callbacks related to Optimization can be found below.

OptimizationListener
onOptimizationProgress
onOptimizationError
onOptimizationStopError
onOptimizationStopGeocode
onOptimizationResult

OptimizationOutStop

Overview
Optimized output stop information including original stop number, optimized stop sequence number, ETA and distance of the stop.
Android Support
>=9.6.0.821
iOS Support
>=10.9
Type
Class
Package
com.alk.cpik.optimization

Public Constructors

Method Name Description
OptimizationOutStop(short, short, short, double) A constructor of OptimizationOutStop with default values.
OptimizationOutStop(Parcel) A constructor of OptimizationOutStop with Parcel object initialization.

Members

Member Name Return Type Description
mStopNo
Short
Stop sequence number provided by CPIK application while sending the optimization request.
mOptimizedStopNo
Short
Optimized stop sequence number. This will only be use in optimization. This will be ignored for ETA calculation.
mEta
Short
ETA based on optimized stop sequence for optimization while given sequence for ETA calculation. (Minutes starting from midnight. For example, 7 a.m. can be represented by 60*7 = 420; 2.30 p.m. can be represented using 60*14 + 30 = 870)
mDistance
double
Whether it is ETA calculation or Optimization. True: It will only do ETA calculation. False: It will do optimization.

Methods

Method Name Return Type Description
getStopNumber ()
Short
Returns a stop number.
getOptimizedStopNumber ()
Short
Returns an optimizedStop number.
getETA ()
Short
Returns an ETA value.
getDistance ()
double
Returns travel distance.

Hooks and Callbacks

Hooks and Callbacks related to Optimization can be found below.

OptimizationListener
onOptimizationProgress
onOptimizationError
onOptimizationStopError
onOptimizationStopGeocode
onOptimizationResult
Last updated July 20, 2021.