Contents
- PortML Spec (Version 0.1)
- Elements
- Module and Their Static Properties
- Infrastructure
About this Spec
This specification provides schema definitions used in the PortML. Please refer to the schema file for PortML PortML.xsd which defines all of the datatypes and base infrastructure types.
The PortML is described using the following format.
<PortML xmlns="http://o2des.com/portml-namespace" (attrA="value")>
<nameA><!-- ?? 1..1 type description of content --><nameA>
<nameB[x]><!-- 0..1 type1|type1 description --></nameB>
<nameC> <!-- 1..* -->
<nameD><!-- 1..1 type>Relevant elements --></nameD>
</nameC>
<name>
Using this format:
- To build a valid XML instance of a resource, simply replace the contents of the elements and attributes with valid content as described by the cardinality, type rules and content description found in the comment in each element;
- Elements are always in the namespace http://o2des.com/portml-namespace. This is usually specified as the default namespace on the root element;
- Element name is case-sensitive (though duplicates that differ only in case are never defined);
- Elements must always appear in the order documented;
- Elements which are not documented in this PortML Spec should not be included in the PortML document;
- Any of the XML elements may have an id attribute to serve as the target of an internal reference;
- Attributes can never be empty. Either they are absent, or they are present with at least one character of non-whitespace content;
- Implementers should trim leading and trailing whitespace before writing and SHOULD trim leading and trailing whitespace when reading attribute values;
- XML comments, processing instructions and formatting are not part of the contents of a resource;
- XML resources MUST be exchanged using UTF-8 encoding. Specifying the character encoding using a
<?xml encoding="UTF-8" ?>processing instruction is optional but recommended; - The MIME-type for this format is
application/xml.
Elements
PortML
| Description | |
|---|---|
| Description | The root element of the PortML document. It contains the PortML document metadata and design layout of the port. |
| Parents | No parents. |
| Child Elements | Metadata , DesignSheet |
| Attributes | 1. xmlns: The namespace, must be ” http://o2des.com/portml-namespace “; 2. Version: By default it is 1.0. |
Example
<PortML xmlns="http://o2des.com/portml-namespace" Version="1.0">
<Metadata Language="en-US">
<Company>National University of Singapore</Company>
<Copyright>(C) 2020 NUS, ISEM, C4NGP</Copyright>
</Metadata>
<DesignSheet>
<PlotScale Value="1000" Unit="meter" />
<Modules />
<Layout>
<Infrastructure>
<Links>
<Paths>
<Path />
</Paths>
</Links>
<Locations>
<Location />
</Locations>
</Infrastructure>
</Layout>
</DesignSheet>
</PortML>
Metadata
| Description | |
|---|---|
| Description | The element describing the author of this PortML document. |
| Parents | PortML |
| Child Elements | Company, Copyright |
| Attributes | 1. Language: The language used in this PortML document. |
Example
<Metadata Language="en-US">
<Company>National University of Singapore</Company>
<Copyright>(C) 2020 NUS, ISEM, C4NGP</Copyright>
</Metadata>
DesignSheet
| Description | |
|---|---|
| Description | The element containing both the module definitions of sea port terminal assets and their locations. |
| Parents | PortML |
| Child Elements | PlotScale , Modules , Layout |
| Attributes | None |
Example
<DesignSheet>
<PlotScale Value="1000" Unit="meter" />
<Modules />
<Layout />
...
</Layout>
</DesignSheet>
PlotScale
| Description | |
|---|---|
| Description | The scale between the unit on screen and the actual unit in the real world. |
| Parents | DesignSheet |
| Child Elements | None |
| Attributes | 1. Value: The scale between the unit on screen and the actual unit in the real world; 2. Unit: Unit used in the real world, by default is meter. |
Example
<PlotScale Value="1000" Unit="meter" />
Modules
| Description | |
|---|---|
| Description | Contains a list of modules for the assets in the sea port. |
| Parents | DesignSheet |
| Child Elements | Module |
| Attributes | None |
Example
<Modules>
<Module ...>
...
</Module>
...
</Modules>
Layout
| Description | |
|---|---|
| Description | Specifies the infrastructure of the sea port. |
| Parents | DesignSheet |
| Child Elements | Infrastructure |
| Attributes | None |
Example
<Layout>
<Infrastructure>
...
</Infrastructure>
</Layout>
Module and Their Static Properties
Terminal
There will be one and only one Terminal module in the same PortML document. It is to specify the boundary of the terminal and to provide static properties which are general to the entire port system.
Children: QuayCrane
| Static Property | Data Type | Description |
|---|---|---|
| NumberOfAGVs | number | Total number of AGVs running inside the terminal. |
| NumberOfQuayCranes | number | Total number of quay cranes available inside the terminal. |
| AnnualTeuRate | number | Number of TEUs handled by the sea port annually. |
| TEUImportRatio | decimal | Ratio of the total TEU which is for importing. |
| TEUExportRatio | decimal | Ratio of the total TEU which is for exporting. |
| TEUInterTerminalRatio | decimal | Ratio of the total TEU which is for inter-terminal transhipment. |
| ConcentrationFactor | decimal | [0.5,1.0]: 0.5 – dispersed (uniform); 1 – concentrated (single nearest point). |
| ConsignmentStrategy | decimal | [0,1]: 0 – 1st carrier, 1 – 2nd carrier, 0.5 – no consignment. |
| ClusterFactor | decimal | [0,1]: 0 – small factor, 1 – big factor (single). |
| BoAThresholdInSecond | decimal | Berth on Arrival threshold in second. |
Example
<Module Type="Terminal" Name="Terminal">
<Children>
<Child ModuleReferenceId="QuayCrane" />
</Children>
<StaticProperties>
<Setter Property="NumberOfAGVs" Value="200" Type="number" />
<Setter Property="NumberOfQuayCranes" Value="100" Type="number" />
<Setter Property="AnnualThroughput" Value="8000000" Type="number" />
<Setter Property="AnnualTeuRate" Value="19000000" Type="number" />
<Setter Property="TEUImportRatio" Value="0.059" Type="decimal" />
<Setter Property="TEUExportRatio" Value="0.053" Type="decimal" />
<Setter Property="TEUInterTerminalRatio" Value="0.1" Type="decimal" />
<Setter Property="ConcentrationFactor" Value="0.6" Type="decimal" />
<Setter Property="ConsignmentStrategy" Value="1.0" Type="decimal" />
<Setter Property="ClusterFactor" Value="0.5" Type="decimal" />
<Setter Property="BoAThresholdInSecond" Value="7200" Type="decimal" />
</StaticProperties>
</Module>
QuayCrane
Quay Crane is a type of port crane that is used to transport containers between ships and the handling yard or vice versa. It can traverse the length of a wharf on a rail track.
| Static Property | Data Type | Description |
|---|---|---|
| LadenFrontHoistSpeed | decimal | The speed of laden front hoist in m/min. |
| UnladenFrontHoistSpeed | decimal | The speed of unladen front hoist in m/min. |
| FrontHoistAcceleration | decimal | The acceleration of the front hoist in m/s2. |
| FrontTrolleySpeed | decimal | The speed of laden front trolley in m/min. |
| FrontTrolleyAcceleration | decimal | The acceleration of the front trolley in m/s2. |
| LadenRearHoistSpeed | decimal | The speed of laden rear hoist in m/min. |
| UnladenRearHoistSpeed | decimal | The speed of unladen rear hoist in m/min. |
| RearHoistAcceleration | decimal | The acceleration of the rear hoist in m/s2. |
| RearTrolleySpeed | decimal | The speed of rear trolley in m/min. |
| RearTrolleyAcceleration | decimal | The acceleration of the rear trolley in m/s2. |
| DistanceToFrontTrolley | decimal | Refer to the graph above. Unit is in m. |
| DistanceToFrontHoistFromFront | decimal | Refer to the graph above. Unit is in m. |
| DistanceToFrontHoistFromRear | decimal | Refer to the graph above. Unit is in m. |
| DistanceToRearTrolley | decimal | Refer to the graph above. Unit is in m. |
| DistanceToRearHoistFromFront | decimal | Refer to the graph above. Unit is in m. |
| DistanceToRearHoistFromRear | decimal | Refer to the graph above. Unit is in m. |
| DistanceBeforeAiming | decimal | Aiming distance in m. |
| SeaSideAimingTimeInSeconds | decimal | Sea side hoist aiming time in s. |
| LandSideAimingTimeInSeconds | decimal | Land side hoist aiming time in s. |
| ConingTimeInSeconds | decimal | The time taken to tranship container from coning platform to set-down or put on the AGV in s. |
| BufferCapacity | decimal | Number of containers allowed in the quay crane buffer. |
| CoefficientVariation | decimal | Coefficient variation used in calculating the time needed for trolley on the quay crane to move from one point to another. |
Example
<Module Type="QuayCrane" Name="Euromax">
<StaticProperties>
<Setter Property="LadenFrontHoistSpeed" Value="90" Type="decimal" />
<Setter Property="UnladenFrontHoistSpeed" Value="180" Type="decimal" />
<Setter Property="FrontHoistAcceleration" Value="0.75" Type="decimal" />
<Setter Property="FrontTrolleySpeed" Value="270" Type="decimal" />
<Setter Property="FrontTrolleyAcceleration" Value="0.67" Type="decimal" />
<Setter Property="LadenRearHoistSpeed" Value="60" Type="decimal" />
<Setter Property="UnladenRearHoistSpeed" Value="120" Type="decimal" />
<Setter Property="RearHoistAcceleration" Value="0.75" Type="decimal" />
<Setter Property="RearTrolleySpeed" Value="180" Type="decimal" />
<Setter Property="RearTrolleyAcceleration" Value="0.6" Type="decimal" />
<Setter Property="BufferDistanceToFrontTrolleyFromFront" Value="7.35" Type="decimal" />
<Setter Property="DistanceToFrontTrolleyFromRear" Value="28.25" Type="decimal" />
<Setter Property="BufferDistanceToFrontHoistFromFront" Value="4.25" Type="decimal" />
<Setter Property="DistanceToFrontHoistFromRear" Value="30.75" Type="decimal" />
<Setter Property="DistanceToRearTrolley" Value="20.25" Type="decimal" />
<Setter Property="DistanceToRearHoistFromFront" Value="3.5" Type="decimal" />
<Setter Property="BufferDistanceToRearHoistFromRear" Value="11.5" Type="decimal" />
<Setter Property="DistanceBeforeAiming" Value="3.5" Type="decimal" />
<Setter Property="SeaSideAimingTimeInSeconds" Value="10" Type="decimal" />
<Setter Property="LandSideAimingTimeInSeconds" Value="5" Type="decimal" />
<Setter Property="ConingTimeInSeconds" Value="5" Type="decimal" />
<Setter Property="BufferCapacity" Value="2" Type="number" />
<Setter Property="CoefficientVariation" Value="0.5" Type="decimal" />
</StaticProperties>
</Module>
YardSet
YardSet module is corresponding to the container yard in the sea port terminal.
Children: YardCrane
| Static Property | Data Type | Description |
|---|---|---|
| NumberOfRows | number | The number of rows in the yard block. |
| NumberOfBays | number | The number of bays in the yard block. |
| NumberOfTiers | number | The number of tiers in the yard block. |
| TotalSlotLength | decimal | The entire length of the yard block at the bay side. |
| TotalSlotWidth | decimal | The entire length of the yard block at the row side. |
| IsLeftWorkingLaneEnabled | boolean | True if there is a working lane at the left of the yard set. |
| IsRightWorkingLaneEnabled | boolean | True if there is a working lane at the right of the yard set. |
| IsForExchange | boolean | True if this yard set is used for container exchange. |
| IsPerpendicular | boolean | True if the rows of the yardset are perpendicular to passing lanes. |
| WorkingLaneYCoordinates | text | The y-axis coordinates of the working lane(s), each value separated by a comma (,). There can be at most 2 values depends on the status of IsLeftWorkingLaneEnabled and IsRightWorkingLaneEnabled. |
| NumberOfExchangeBays | number | Number of exchange bays in the yard set. It should be 0 if the IsForExchange is False. |
| FacingDirection | number | Currently supports only 0 (facing up) and 180 (facing down). |
| EndLotsPosition | endlotsposition | Currently supports None (not having any end lots), Head (end lots positioned before the yard set), and Tail (end lots positioned after the yard set). |
Example
<Module Type="YardSet" Name="YardSet11x49_P*WL2_180">
<Children>
<Child ModuleReferenceId="YardBlock11x49" />
<Child ModuleReferenceId="YC_RMG_WH_Base_11" />
<Child ModuleReferenceId="YC_RMG_WH_Base_11" />
</Children>
<StaticProperties>
<Setter Property="NumberOfBays" Value="49" Type="number" />
<Setter Property="NumberOfTiers" Value="6" Type="number" />
<Setter Property="NumberOfRows" Value="11" Type="number" />
<Setter Property="TotalSlotLength" Value="322.4520" Type="decimal" />
<Setter Property="TotalSlotWidth" Value="31.34" Type="decimal" />
<Setter Property="IsLeftWorkingLaneEnabled" Value="True" Type="boolean" />
<Setter Property="IsRightWorkingLaneEnabled" Value="True" Type="boolean" />
<Setter Property="IsForExchange" Value="False" Type="boolean" />
<Setter Property="IsPerpendicular" Value="True" Type="boolean" />
<Setter Property="WorkingLaneYCoordinates" Value="-5.5,36.84" Type="text" />
<Setter Property="NumberOfExchangeBays" Value="0" Type="number" />
<Setter Property="FacingDirection" Value="180" Type="number" />
<Setter Property="EndLotsPosition" Value="None" Type="endlotsposition" />
</StaticProperties>
</Module>
YardCrane
Yard crane consists of gantry, trolley, and hoist as one component. Each yard set can have 0 or above yard crane.
| Static Property | Data Type | Description |
|---|---|---|
| MaximumHeight | decimal | The maximum height of the yard crane in meter. |
| AimingDistance | decimal | The distance in meter between the hoist and the top of the container when it starts to proceed to pick up the container. |
| GantrySpeed | decimal | The maximum uniform speed of the gantry movement in m/s. |
| GantryAcceleration | decimal | The acceleration of the gantry in m/s2. |
| GantryDeceleration | decimal | The deceleration of the gantry in m/s2. |
| TrolleySpeed | decimal | The speed of the trolley in m/s. |
| TrolleyAcceleration | decimal | The acceleration of the trolley in m/s2. |
| TrolleyDeceleration | decimal | The deceleration of the trolley in m/s2. |
| LadenHoistSpeed | decimal | The maximum uniform speed of the laden hoist in m/s. |
| LadenHoistAcceleration | decimal | The acceleration of the laden hoist in m/s2. |
| LadenHoistDeceleration | decimal | The deceleration of the laden hoist in m/s2. |
| UnladenHoistSpeed | decimal | The maximum uniform speed of the unladen hoist in m/s. |
| UnladenHoistAcceleration | decimal | The acceleration of the unladen hoist in m/s2. |
| UnladenHoistDeceleration | decimal | The deceleration of the unladen hoist in m/s2. |
| CoefficientVariation | decimal | CV of the distribution used to determine the time of movement of the gantry, trolley, and hoist. |
Example
<Module Type="YardCrane" Name="YC_RMG_WH_Base_11">
<StaticProperties>
<Setter Property="MaximumHeight" Value="10" Type="decimal" />
<Setter Property="AimingDistance" Value="3.5" Type="decimal" />
<Setter Property="GantrySpeed" Value="45" Type="decimal" />
<Setter Property="GantryAcceleration" Value="0.125" Type="decimal" />
<Setter Property="GantryDeceleration" Value="0.125" Type="decimal" />
<Setter Property="TrolleySpeed" Value="240" Type="decimal" />
<Setter Property="TrolleyAcceleration" Value="0.67" Type="decimal" />
<Setter Property="TrolleyDeceleration" Value="0.67" Type="decimal" />
<Setter Property="LadenHoistSpeed" Value="60" Type="decimal" />
<Setter Property="LadenHoistAcceleration" Value="0.6" Type="decimal" />
<Setter Property="LadenHoistDeceleration" Value="0.6" Type="decimal" />
<Setter Property="UnladenHoistSpeed" Value="120" Type="decimal" />
<Setter Property="UnladenHoistAcceleration" Value="0.6" Type="decimal" />
<Setter Property="UnladenHoistDeceleration" Value="0.6" Type="decimal" />
<Setter Property="CoefficientVariation" Value="0" Type="decimal" />
</StaticProperties>
</Module>
Wharf
Wharf is the side of the port terminal where vessels will be parked at. Quay cranes will be located at the land side of the wharf.
| Static Property | Data Type | Description |
|---|---|---|
| Length | decimal | Total length of the wharf. |
| Facing | decimal | Direction of the wharf. Rotating point is at the starting point of the wharf. |
| WaitingAreaDistanceFromSeaSide | decimal | The distance between the wharf and the AGV waiting area along the wharf. |
| WaitingAreaStartPosition | decimal | The X coordinate of the starting position of the AGV waiting area along the wharf. |
| WaitingAreaEndPosition | decimal | The X coordinate of the ending position of the AGV waiting area along the wharf. |
| WaitingAreaCapacity | number | Number of AGVs that can be parked at the waiting area along the wharf. |
Example
<Module Type="Wharf" Name="Wharf0">
<StaticProperties>
<Setter Property="Length" Value="3145" Type="decimal" />
<Setter Property="Facing" Value="0" Type="decimal" />
<Setter Property="WaitingAreaDistanceFromSeaSide" Value="73.5" Type="decimal" />
<Setter Property="WaitingAreaStartPosition" Value="8.11" Type="decimal" />
<Setter Property="WaitingAreaEndPosition" Value="3152.11" Type="decimal" />
<Setter Property="WaitingAreaCapacity" Value="393" Type="number" />
</StaticProperties>
</Module>
Dispatcher
Job dispatcher is responsible to distribute and allocate jobs to the AGVs.
| Static Property | Data Type | Description |
|---|---|---|
| LeadTimeInSecond | decimal | Lead time of each job allocation in seconds. |
| TargetQCMovesPerHour | decimal | Average number of jobs accomplished by a quay crane per hour. |
| LimitPerQC | number | The maximum AGVs to be assigned to each of the quay crane. |
| EstimatedAverageSpeed | decimal | Estimated average speed of an AGV travel from a control point to another. |
| AvoidanceFactor | decimal | Used in calculating the exchanged or transhipment yard points to be avoided during job allocation. |
Example
<Module Type="Dispatcher" Name="JobDispatcher">
<StaticProperties>
<Setter Property="LeadTimeInSecond" Value="1800" Type="decimal" />
<Setter Property="TargetQCMovesPerHour" Value="40" Type="number" />
<Setter Property="LimitPerQC" Value="6" Type="number" />
<Setter Property="EstimatedAverageSpeed" Value="4.5" Type="decimal" />
<Setter Property="AvoidanceFactor" Value="0" Type="decimal" />
</StaticProperties>
</Module>
Vessel
Vessel is the container vessel doing the import and export with the port container.
| Static Property | Data Type | Description |
|---|---|---|
| AnnualArrivalRate | decimal | The number of times the vessel with arrive at the port annually. |
| LengthOverall_Triangular_Lower | decimal | The lower limit of Triangular distribution applied in calculating the LOA (Length Overall) of the vessel. |
| LengthOverall_Triangular_Upper | decimal | The upper limit of Triangular distribution applied in calculating the LOA (Length Overall) of the vessel. |
| LengthOverall_Triangular_Mode | decimal | The mode of Triangular distribution applied in calculating the LOA (Length Overall) of the vessel. |
| MeanTeu | decimal | Mean TEUs available on the vessel. |
| CoefficientVariation | decimal | Coefficient variation used to calculate the inter arrival time of the vessel. |
| Cell_BaseX | decimal | Base X coordinate of the cells in the vessel. |
| Cell_BaseY | decimal | Base Y coordinate of the cells in the vessel. |
| Cell_NumberOfTiers | decimal | Number of tiers for all the cells in the container |
| Cell_TwinLiftRatio_Discharging | decimal | Twin Lift Ratio for discharging the containers from the vessel. |
| Cell_TwinLiftRatio_Loading | decimal | Twin Lift Ratio for loading the containers to the vessel. |
Example
<Module Type="Vessel" Name="Vessel4">
<StaticProperties>
<Setter Property="AnnualArrivalRate" Value="25" Type="decimal" />
<Setter Property="LengthOverall_Triangular_Lower" Value="269" Type="decimal" />
<Setter Property="LengthOverall_Triangular_Upper" Value="400" Type="decimal" />
<Setter Property="LengthOverall_Triangular_Mode" Value="293" Type="decimal" />
<Setter Property="MeanTeu" Value="2892" Type="decimal" />
<Setter Property="CoefficientVariation" Value="0.3" Type="decimal" />
<Setter Property="Cell_BaseX" Value="0.3" Type="decimal" />
<Setter Property="Cell_BaseY" Value="0.5" Type="decimal" />
<Setter Property="Cell_NumberOfTiers" Value="23" Type="number" />
<Setter Property="Cell_TwinLiftRatio_Discharging" Value="0.74" Type="decimal" />
<Setter Property="Cell_TwinLiftRatio_Loading" Value="0.74" Type="decimal" />
</StaticProperties>
</Module>
Infrastructure
Path
The path the AGVs can travel on in the port terminal are categorised into different types, i.e. TwoWayWorkingLane, WorkingLane, PassingLane, and PerpendicularTwoWayWorkingLane.
| Attribute | Description |
|---|---|
| Type | Type of the path. It can only be TwoWayWorkingLane, WorkingLane, PassingLane, and PerpendicularTwoWayWorkingLane. |
| StartingPoint | The x,y coordinate value of the starting of the path. |
| EndingPoint | The x,y coordinate value of the ending of the module. |
| NumberOfLanes | The total number of lanes in the path that the AGVs can travel on. |
| NumberOfGaps | Number of gaps determine the number of control points in the path. Normally, the number of control points equals to the number of gaps + 1. |
| Tags | Tags that will be assigned to the control points on the path, each tag is separated by a comma(,). For the PerpendicularTwoWayWorkingLane, we can assign two groups of tags to those two ways, each group is separated by an underscore(_). |
| OffsetX | Offset of the path in X-axis. |
| OffsetY | Offset of the path in Y-axis. |
Example
<Locations>
<Path Type="TwoWayWorkingLane" StartingPoint="8,12" EndingPoint="3502.7008,12" NumberOfLanes="3" NumberOfGaps="0" Tags="Q" OffsetX="0" OffsetY="-6" />
...
</Locations>
Location
Each individual wharf and yard set in the port terminal will have its own Location element.
| Attribute | Description |
|---|---|
| ReferenceId | The name of the module this location is corresponding to. |
| Coordinate | The x,y coordinate value of the starting of the module. The x and y values are separated by comma. |
Example
<Locations>
<Location ReferenceId="Wharf1_P" Coordinate="8.11,-86" />
...
<Location ReferenceId="YardSet11x49_P*WLR" Coordinate="1065.16,42.0056" />
</Locations>