New roles/capabilities approach in Actions:

- Updated actions.yaml (half way done) to use a nested roles->capabilities
  dictionary rather than requirements and capabilities lists.
- Actions class now has assets and requirements dicts that correspond
  to roles/capabilities in the YAML.
- Draft outlines of Action methods assignAsset and checkAsset

Author: mattEhall

famodel/irma/action.py

@@ -87,7 +87,8 @@ def __init__(self, actionType, name, **kwargs):
         '''
 
         # list of things that will be controlled during this action
-        self.vesselList   = []  # all vessels required for the action
+        self.assets = {}  # dict of named roles for the vessel(s) or port required to perform the action
+        self.requirements = {}  # the capabilities required of each asset role assets (same keys as self.assets)
         self.objectList   = []  # all objects that could be acted on
         self.dependencies = {}  # list of other actions this one depends on
 
@@ -123,6 +124,7 @@ def __init__(self, actionType, name, **kwargs):
                 supported_objects = list(actionType['objects'].keys())
         else:
             supported_objects = []
+        
         # Add objects to the action's object list as long as they're supported
         if 'objects' in kwargs:
             for obj in kwargs['objects']:
@@ -131,7 +133,15 @@ def __init__(self, actionType, name, **kwargs):
                     self.objectList.append(obj)
                 else:
                     raise Exception(f"Object type '{objType}' is not in the action's supported list.")
-                
+        
+        # Create placeholders for asset roles based on the "requirements"
+        if 'roles' in actionType:
+            for asset, caplist in actionType['roles'].items():
+                self.assets[asset] = None  # each asset role holds a None value until assigned
+                self.requirements[asset] = {}
+                for cap in caplist:
+                    self.requirements[asset][cap] = 0  # fill in each required metric with zero to start with?
+                    
 
         # Process dependencies
         if 'dependencies' in kwargs:
@@ -149,22 +159,61 @@ def addDependency(self, dep):
         # could see if already a dependency and raise a warning if so...
 
 
+    def checkAsset(self, role_name, asset):
+        '''Checks if a specified asset has sufficient capabilities to fulfil
+        a specified role in this action.
+        '''
+        
+        # Make sure role_name is valid for this action
+        if not role_name in self.assets.keys():
+            raise Exception(f"The specified role name '{role_name}' is not a named asset role in this action.")
+        
+        for cap, req in self.requirements['role_name']:
+            if asset.capabilities[cap] >= req:  # <<< this is pseudocode. Needs to look at capability numbers! <<<
+                pass
+                # so far so good
+            else:
+                return False  # at least on capability is not met, so return False
+                
+        return True
 
-    def assignAssets(self, assets):
-        pass
+    
+    def assignAsset(self, role_name, asset):
+        '''Assigns a vessel or port to a certain role in the action.
+        
+        Parameters
+        ----------
+        role_name : string
+            Name of the asset role being filled (must be in the action's list)
+        asset : Vessel or Port object
+            The asset to be registered with the class.
+        '''
+        
+        # Make sure role_name is valid for this action
+        if not role_name in self.assets.keys():
+            raise Exception(f"The specified role name '{role_name}' is not a named asset role in this action.")
+        
+        self.assets[role_name] = asset
+        
 
     def calcDurationAndCost(self):
         pass
 
-    def evaluateAsset(self, assets):
+    
+    def evaluateAssets(self, assets):
         '''Check whether an asset can perform the task, and if so calculate
-        the time and cost associated with using that vessel.
-        asset : vessel or port object(s)
+        the time and cost associated with using those assets.
+        
+        assets : dict
+            Dictionary of role_name, asset object pairs for assignment to the action.
+            Each asset is a vessel or port object.
         
         '''
-        pass
 
-        self.assignAssets(assets)
+        # Assign each specified asset to its respective role
+        for akey, aval in assets.items():
+            self.assignAsset(akey, aval)
+            
         self.calcDurationAndCost()
 
 
@@ -173,7 +222,7 @@ def evaluateAsset(self, assets):
 
 
     # ----- Below are drafts of methods for use by the engine -----
-    
+    """
     def begin(self):
         '''Take control of all objects'''
         for vessel in self.vesselList:
@@ -188,36 +237,36 @@ def end(self):
             vessel._detach_from()
         for object in self.objectList:
             object._detach_from()
-        
+    """
 
     def timestep(self):
         '''Advance the simulation of this action forward one step in time.'''
 
         # (this is just documenting an idea for possible future implementation)
         # Perform the hourly action of the task
-        '''
+        
         if self.type == 'tow':
             # controller - make sure things are going in right direction...
             # (switch mode if need be)
             if self.mode == 0 :  # gathering vessels
-                for ves in self.vesselList:
-                    dr = self.r_start - ves.r
-                    ves.setCourse(dr)  # sets vessel velocity
+                ves = self.assets['vessel']
+                dr = self.r_start - ves.r
+                ves.setCourse(dr)  # sets vessel velocity
 
-                # if all vessels are stopped (at the object), time to move
-                if all([np.linalg.norm(ves.v) == 0 for ves in self.vesselList]):
+                # if vessel is stopped (at the object), time to move
+                if np.linalg.norm(ves.v) == 0:
                     self.mode = 1
 
             if self.mode == 1:  # towing
-                for ves in self.vesselList:
-                    dr = self.r_finish - ves.r
-                    ves.setCourse(dr)  # sets vessel velocity
+                ves = self.assets['vessel']
+                dr = self.r_finish - ves.r
+                ves.setCourse(dr)  # sets vessel velocity
 
                 # if all vessels are stopped (at the final location), time to end
-                if all([np.linalg.norm(ves.v) == 0 for ves in self.vesselList]):
+                if np.linalg.norm(ves.v) == 0:
                     self.mode = 2
 
             if self.mode == 2:  # finished
                 self.end()
-        '''
+        
 

famodel/irma/actions.yaml

@@ -1,13 +1,17 @@
 # This file defines standardized marine operations actions.
 # Each entry needs numeric values per specific asset in vessels.yaml.
 # Vessel actions will be checked against capabilities/actions for validation.
+#
+#  Old format: requirements and capabilities 
+#  New format: roles, which lists asset roles, each with associated required capabilities
 
 # --- Towing & Transport ---
 
 tow:
   objects: [platform]
   requirements: [TUG]
-  capabilities:
+  roles:  # The asset roles involved and the capabilities required of each role
+    vessel:
     - deck_space
     - bollard_pull
     - winch
@@ -19,7 +23,8 @@ tow:
 transport_components:
   objects: [component]
   requirements: [HL, WTIV, CSV]
-  capabilities:
+  roles:  # The asset roles involved and the capabilities required of each role
+    carrier:  # vessel carrying things
     - deck_space
     - crane
     - positioning_system
@@ -32,8 +37,10 @@ transport_components:
 install_anchor:
   objects: [anchor]
   requirements: [AHTS, MSV]
-  capabilities:
+  roles:  # The asset roles involved and the capabilities required of each role
+    carrier:  # vessl that has been carrying the anchor
     - deck_space
+    operator:  # vessel that lowers and installs the anchor
     - winch
     - bollard_pull
     - crane
@@ -47,8 +54,10 @@ install_anchor:
 retrieve_anchor:
   objects: [anchor]
   requirements: [AHTS, MSV]
-  capabilities:
+  roles:  # The asset roles involved and the capabilities required of each role
+    carrier:
     - deck_space
+    operator:
     - winch
     - bollard_pull
     - crane
@@ -57,25 +66,31 @@ retrieve_anchor:
   duration_h: 4
   Hs_m:: 2.5
   description: "Anchor retrieval, including break-out and recovery to deck."
-  
+
+
 load_mooring:
   objects: [mooring]
-  requirements: [port, vessel]
-  capabilities:
+  roles:  # The asset roles involved and the capabilities required of each role
+    carrier1: [] # the port or vessel where the moorings begin
+      # (no requirements)
+    carrier2:  # the vessel things will be loaded onto
     - deck_space
     - winch
-    - bollard_pull
-    - mooring_work
     - positioning_system
+    operator:  # the entity with the crane (like the port or the new vessel)
+    - crane  
   duration_h: 2
   Hs_m:: 2.5
-  description: "Load-out of mooring lines and components from port or vessel onto vessel."    
+  description: "Load-out of mooring lines and components from port or vessel onto vessel." 
+
 
 lay_mooring:
   objects: [mooring]
   requirements: [AHTS, CSV]
-  capabilities:
+  roles:  # The asset roles involved and the capabilities required of each role
+    carrier:  # vessel carrying the mooring
     - deck_space
+    operator:  # vessel laying the mooring
     - winch
     - bollard_pull
     - mooring_work
@@ -84,13 +99,16 @@ lay_mooring:
   Hs_m:: 2.5
   description: "Laying mooring lines, tensioning and connection to anchors and floaters."
 
+
 mooring_hookup:
   objects:
     mooring: [pretension]
     platform: [wec]
   requirements: [AHTS, CSV]
-  capabilities:
+  roles:  # The asset roles involved and the capabilities required of each role
+    carrier:
     - deck_space
+    operator:
     - winch
     - bollard_pull
     - mooring_work

famodel/irma/capabilities.yaml

@@ -2,6 +2,9 @@
 # Each entry needs numeric values per specific asset in vessels.yaml.
 # Vessel actions will be checked against capabilities/actions for validation.
 
+# >>> Units to be converted to standard values, with optional converter script
+# for allowing conventional unit inputs. <<<
+
 # --- Vessel (on-board) ---
 
  - name: deck_space

famodel/irma/irma.py

@@ -145,10 +145,12 @@ def __init__(self):
             #    raise Exception(f"Action key ({key}) contradicts its name ({act['name']})")
 
             # Check capabilities
-            if not 'capabilities' in act:
-                raise Exception(f"Action '{key}' is missing a capabilities list.")
+            #if 'capabilities' in act:
+            #    raise Exception(f"Action '{key}' is missing a capabilities list.")
+            
+            if 'capabilities' in act:
 
-            for cap in act['capabilities']:
+              for cap in act['capabilities']:
                 if not cap in capabilities:
                     raise Exception(f"Action '{key}' capability '{cap}' is not in the global capability list.")
 
@@ -157,6 +159,13 @@ def __init__(self):
                 #    if not cap_param in capabilities[cap['name']]:
                 #        raise Exception(f"Action '{key}' capability '{cap['name']}' parameter '{cap_param}' is not in the global capability's parameter list.")
 
+            if 'roles' in act:   # look through capabilities listed under each role
+                for caps in act['roles'].values():
+                    for cap in caps:
+                        if not cap in capabilities:
+                            raise Exception(f"Action '{key}' capability '{cap}' is not in the global capability list.")
+                        
+            
             # Check objects
             if not 'objects' in act:
                 raise Exception(f"Action '{key}' is missing an objects list.")