fameio 3.3.0__py3-none-any.whl → 3.4.0__py3-none-any.whl

fameio/input/scenario/contract.py

@@ -10,7 +10,7 @@ from fameio.input.metadata import Metadata
 from fameio.input.scenario.attribute import Attribute
 from fameio.logs import log, log_error
 from fameio.time import FameTime, ConversionError
-from fameio.tools import ensure_is_list, keys_to_lower
+from fameio.tools import keys_to_lower
 
 
 class Contract(Metadata):
@@ -24,6 +24,7 @@ class Contract(Metadata):
     KEY_PRODUCT: Final[str] = "ProductName".lower()
     KEY_FIRST_DELIVERY: Final[str] = "FirstDeliveryTime".lower()
     KEY_INTERVAL: Final[str] = "DeliveryIntervalInSteps".lower()
+    KEY_EVERY: Final[str] = "Every".lower()
     KEY_EXPIRE: Final[str] = "ExpirationTime".lower()
     KEY_ATTRIBUTES: Final[str] = "Attributes".lower()
 
@@ -33,7 +34,8 @@ class Contract(Metadata):
         "or N-to-N sender-to-receiver numbers. Found M-to-N pairing in Contract with "
         "Senders: {} and Receivers: {}."
     )
-    _ERR_INTERVAL_NOT_POSITIVE = "Contract delivery interval must be a positive integer but was: {}"
+    _ERR_XOR_KEYS = "Contract expects exactly one of the keys '{}' or '{}'. Found either both or none."
+    _ERR_INTERVAL_INVALID = "Contract delivery interval must be a positive integer but was: {}"
     _ERR_SENDER_IS_RECEIVER = "Contract sender and receiver have the same id: {}"
     _ERR_DOUBLE_ATTRIBUTE = "Cannot add attribute '{}' to contract because it already exists."
     _ERR_TIME_CONVERSION = "Contract item '{}' is an ill-formatted time: '{}'"
@@ -73,7 +75,7 @@ class Contract(Metadata):
         if sender_id == receiver_id:
             log().warning(self._ERR_SENDER_IS_RECEIVER.format(sender_id))
         if delivery_interval <= 0:
-            raise log_error(self.ContractError(self._ERR_INTERVAL_NOT_POSITIVE.format(delivery_interval)))
+            raise log_error(self.ContractError(self._ERR_INTERVAL_INVALID.format(delivery_interval)))
         self._sender_id = sender_id
         self._receiver_id = receiver_id
         self._product_name = product_name
@@ -164,7 +166,7 @@ class Contract(Metadata):
         product_name = Contract._get_or_raise(definitions, Contract.KEY_PRODUCT, Contract._ERR_MISSING_KEY)
 
         first_delivery_time = Contract._get_time(definitions, Contract.KEY_FIRST_DELIVERY)
-        delivery_interval = Contract._get_or_raise(definitions, Contract.KEY_INTERVAL, Contract._ERR_MISSING_KEY)
+        delivery_interval = Contract._get_interval(definitions)
         expiration_time = Contract._get_time(definitions, Contract.KEY_EXPIRE, mandatory=False)
 
         contract = cls(sender_id, receiver_id, product_name, delivery_interval, first_delivery_time, expiration_time)
@@ -224,6 +226,43 @@ class Contract(Metadata):
             raise log_error(Contract.ContractError(Contract._ERR_MISSING_KEY.format(key)))
         return None
 
+    @staticmethod
+    def _get_interval(definitions: dict) -> int:
+        """Extract delivery interval from Contract definition, or raise an error if not present or ill formatted.
+
+        Args:
+            definitions: to extract the delivery interval from
+
+        Returns:
+            the delivery interval in fame time steps
+
+        Raises:
+            ContractError: if delivery interval is not defined or invalid, logged with level "ERROR"
+        """
+        has_interval = Contract.KEY_INTERVAL in definitions
+        has_every = Contract.KEY_EVERY in definitions
+
+        if has_interval and not has_every:
+            value = definitions[Contract.KEY_INTERVAL]
+            if isinstance(value, int):
+                return value
+            raise log_error(Contract.ContractError(Contract._ERR_INTERVAL_INVALID.format(value)))
+        if has_every and not has_interval:
+            value = definitions[Contract.KEY_EVERY]
+            if isinstance(value, int):
+                return value
+            if isinstance(value, str):
+                try:
+                    return FameTime.convert_text_to_time_span(value)
+                except ConversionError as e:
+                    raise log_error(
+                        Contract.ContractError(Contract._ERR_TIME_CONVERSION.format(Contract.KEY_EVERY, value))
+                    ) from e
+            raise log_error(Contract.ContractError(Contract._ERR_TIME_CONVERSION.format(Contract.KEY_EVERY, value)))
+        raise log_error(
+            Contract.ContractError(Contract._ERR_XOR_KEYS.format(Contract.KEY_INTERVAL, Contract.KEY_EVERY))
+        )
+
     def _init_attributes_from_dict(self, attributes: dict[str, Any]) -> None:
         """Resets Contract `attributes` from dict.
 
@@ -280,15 +319,14 @@ class Contract(Metadata):
             Contract.KEY_EXPIRE,
             Contract.KEY_METADATA,
             Contract.KEY_ATTRIBUTES,
+            Contract.KEY_EVERY,
         ]:
             if key in multi_definition:
                 base_data[key] = multi_definition[key]
-        senders = ensure_is_list(
-            Contract._get_or_raise(multi_definition, Contract.KEY_SENDER, Contract._ERR_MISSING_KEY)
-        )
-        receivers = ensure_is_list(
-            Contract._get_or_raise(multi_definition, Contract.KEY_RECEIVER, Contract._ERR_MISSING_KEY)
-        )
+        sender_value = Contract._get_or_raise(multi_definition, Contract.KEY_SENDER, Contract._ERR_MISSING_KEY)
+        senders = Contract._unpack_list(sender_value)
+        receiver_value = Contract._get_or_raise(multi_definition, Contract.KEY_RECEIVER, Contract._ERR_MISSING_KEY)
+        receivers = Contract._unpack_list(receiver_value)
         if len(senders) > 1 and len(receivers) == 1:
             for index, sender in enumerate(senders):
                 contracts.append(Contract._copy_contract(sender, receivers[0], base_data))
@@ -302,6 +340,13 @@ class Contract(Metadata):
             raise log_error(Contract.ContractError(Contract._ERR_MULTI_CONTRACT_CORRUPT.format(senders, receivers)))
         return contracts
 
+    @staticmethod
+    def _unpack_list(obj: Any | list) -> list[Any]:
+        """Returns the given value as a flat list - unpacks potential nested list(s)"""
+        if isinstance(obj, list):
+            return [item for element in obj for item in Contract._unpack_list(element)]
+        return [obj]
+
     @staticmethod
     def _copy_contract(sender: int, receiver: int, base_data: dict) -> dict:
         """Returns a new contract definition dictionary, with given `sender` and `receiver` and copied `base_data`."""

fameio/time.py

@@ -17,6 +17,7 @@ START_IN_REAL_TIME = "2000-01-01_00:00:00"
 DATE_FORMAT = "%Y-%m-%d_%H:%M:%S"
 DATE_REGEX = re.compile("[0-9]{4}-[0-9]{2}-[0-9]{2}_[0-9]{2}:[0-9]{2}:[0-9]{2}")
 FAME_FIRST_DATETIME = dt.datetime.strptime(START_IN_REAL_TIME, DATE_FORMAT)
+TIME_SPAN_REGEX = re.compile(r"^[0-9]+\s*[A-z]+$")
 
 
 class ConversionError(InputError, OutputError):
@@ -71,6 +72,8 @@ class FameTime:
     _INVALID_TOO_LARGE = "Cannot convert time stamp string '{}' - last day of leap year is Dec 30th!"
     _NO_TIMESTAMP = "Time value expected, but '{}' is neither a time stamp string nor an integer."
     _INVALID_DATE_FORMAT = "Received invalid date format '{}'."
+    _INVALID_SPAN_FORMAT = "Time span must be provided in the format '<positive integer> <TimeUnit>' but was: '{}'"
+    _INVALID_TIME_UNIT = f"Time span unit '{{}}' unknown, must be one of: {[u.name for u in TimeUnit]}"
 
     @staticmethod
     def convert_datetime_to_fame_time_step(datetime_string: str) -> int:
@@ -160,6 +163,32 @@ class FameTime:
             return steps * value
         raise log_error(ConversionError(FameTime._TIME_UNIT_UNKNOWN.format(unit)))
 
+    @staticmethod
+    def convert_text_to_time_span(string: str) -> int:
+        """Converts given string in form of "<positive integer> <TimeUnit>" to a time span in FAME time steps.
+
+        Args:
+            string: to convert to a time span from
+
+        Returns:
+            FAME time steps equivalent of `value x unit`
+
+        Raises:
+            ConversionError: if an unknown time unit or an unsupported format is used, logged with level "ERROR"
+        """
+        string = string.strip()
+        if TIME_SPAN_REGEX.fullmatch(string) is None:
+            raise log_error(ConversionError(FameTime._INVALID_SPAN_FORMAT.format(string)))
+        multiple, unit_name = string.split()
+        unit_name = unit_name.upper()
+        if not unit_name.endswith("S"):
+            unit_name += "S"
+        try:
+            unit = TimeUnit[unit_name]
+        except KeyError as e:
+            raise log_error(ConversionError(FameTime._INVALID_TIME_UNIT.format(unit_name))) from e
+        return FameTime.convert_time_span_to_fame_time_steps(int(multiple), unit)
+
     @staticmethod
     def is_datetime(string: Any) -> bool:
         """Returns `True` if given `string` matches Datetime string format and can be converted to FAME time step."""
@@ -208,3 +237,15 @@ class FameTime:
             return int(value)
         except ValueError as e:
             raise log_error(ConversionError(FameTime._NO_TIMESTAMP.format(value))) from e
+
+    @staticmethod
+    def get_first_fame_time_step_of_year(year: int) -> int:
+        """Returns FAME time in integer format of first time step of given year.
+
+        Args:
+            year: to get the first time step for
+
+        Returns:
+            first time step in the requested year in integer format
+        """
+        return (year - FAME_FIRST_DATETIME.year) * Constants.STEPS_PER_YEAR

{fameio-3.3.0.dist-info → fameio-3.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: fameio
-Version: 3.3.0
+Version: 3.4.0
 Summary: Tools for input preparation and output digestion of FAME models
 License: Apache-2.0
 Keywords: FAME,fameio,agent-based modelling,energy systems
@@ -507,7 +507,7 @@ Contracts:
     ReceiverId: 2
     ProductName: ProductOfAgent_1
     FirstDeliveryTime: -25
-    DeliveryIntervalInSteps: 3600
+    Every: 3600
     Metadata:
       Some: "additional information can go here"
 
@@ -515,7 +515,7 @@ Contracts:
     ReceiverId: 1
     ProductName: ProductOfAgent_2
     FirstDeliveryTime: -22
-    DeliveryIntervalInSteps: 3600
+    Every: 1 hour
     Attributes:
       ProductAppendix: value
       TimeOffset: 42
@@ -527,7 +527,8 @@ Contract Parameters:
 * `ReceiverId` unique ID of agent receiving the product
 * `ProductName` name of the product to be sent
 * `FirstDeliveryTime` first time of delivery in the format "seconds after the January 1st 2000, 00:00:00"
-* `DeliveryIntervalInSteps` delay time in between deliveries in seconds
+* `Every` delay time in between deliveries; either an integer value in seconds, or a qualified time span in the format "<integer> <TimeUnit>(s)", where TimeUnit is one of "second", "minute", "hour", "day", "week", "month", "year" - with an options "s" at the end; mind that week, month, and year refer to fixed-length intervals of 168, 730, and 8760 hours.
+* `DeliveryIntervalInSteps` deprecated; delay time in between deliveries in seconds (use instead of `Every`)
 * `Metadata` can be assigned to add further helpful information about a Contract
 * `Attributes` can be set to include additional information as `int`, `float`, `enum`, or `dict` data types
 
@@ -541,59 +542,72 @@ example:
 ```yaml
 Contracts:
   # effectively 3 similar contracts (0 -> 11), (0 -> 12), (0 -> 13)
-  # with otherwise identical ProductName, FirstDeliveryTime & DeliveryIntervalInSteps
+  # with otherwise identical ProductName, FirstDeliveryTime, and Every
   - SenderId: 0
     ReceiverId: [ 11, 12, 13 ]
     ProductName: MyOtherProduct
     FirstDeliveryTime: 100
-    DeliveryIntervalInSteps: 3600
+    Every: 1 hour
 
   # effectively 3 similar contracts (1 -> 10), (2 -> 10), (3 -> 10)
-  # with otherwise identical ProductName, FirstDeliveryTime & DeliveryIntervalInSteps
+  # with otherwise identical ProductName, FirstDeliveryTime, and Every
   - SenderId: [ 1, 2, 3 ]
     ReceiverId: 10
     ProductName: MyProduct
     FirstDeliveryTime: 100
-    DeliveryIntervalInSteps: 3600
+    Every: 1 hour
 
   # effectively 3 similar contracts (1 -> 11), (2 -> 12), (3 -> 13)
-  # with otherwise identical ProductName, FirstDeliveryTime & DeliveryIntervalInSteps
+  # with otherwise identical ProductName, FirstDeliveryTime, and Every
   - SenderId: [ 1, 2, 3 ]
     ReceiverId: [ 11, 12, 13 ]
     ProductName: MyThirdProduct
     FirstDeliveryTime: 100
-    DeliveryIntervalInSteps: 3600
+    Every: 1 hour
 ```
 
-Combined with YAML anchors complex contract chains can be easily reduced to a minimum of required configuration.
-The following example is equivalent to the previous one and allows a quick extension of contracts to a new couple of
-agents e.g. (4;14):
+When combined with YAML anchors, the complexity of extensive contract chains can be reduced.
+The following example is equivalent to the previous one, enabling contracts to be quickly extended to a new group of agents:
 
 ```yaml
 Groups:
-  - &agentList1: [ 1,2,3 ]
-  - &agentList2: [ 11,12,13 ]
+  - &agentList1: [ 1, 2, 3 ]
+  - &agentList2: [ 11, 12, 13 ]
 
 Contracts:
   - SenderId: 0
     ReceiverId: *agentList2
     ProductName: MyOtherProduct
     FirstDeliveryTime: 100
-    DeliveryIntervalInSteps: 3600
+    Every: 1 hour
 
   - SenderId: *agentList1
     ReceiverId: 10
     ProductName: MyProduct
     FirstDeliveryTime: 100
-    DeliveryIntervalInSteps: 3600
+    Every: 1 hour
 
   - SenderId: *agentList1
     ReceiverId: *agentList2
     ProductName: MyThirdProduct
     FirstDeliveryTime: 100
-    DeliveryIntervalInSteps: 3600
+    Every: 1 hour
 ```
 
+Lists can be nested in senders and receivers as follows:
+
+```
+Groups:
+  - SenderId: 42
+    ReceiverId: [1, [2, 3], [4, [5]]]
+    ProductName: AnImportantProduct
+    FirstDeliveryTime: 101
+    Every: 30 minutes
+```
+
+This feature should not be overused, as nested lists can become messy and difficult to read.
+Special care should be taken when using it with an N-to-N mapping, as it will be difficult to check whether senders and receivers are matched correctly.
+
 #### StringSets
 
 This optional section defines values of type `string_set`.

{fameio-3.3.0.dist-info → fameio-3.4.0.dist-info}/RECORD

@@ -14,7 +14,7 @@ fameio/input/resolver.py,sha256=NakBjnCCWRMz-8gTC_Ggx-2tXq-u6OPjfBOua0Rd2nA,1902
 fameio/input/scenario/__init__.py,sha256=Pb8O9rVOTwEo48WIgiq1kBnpovpc4D_syC6EjTFGHew,404
 fameio/input/scenario/agent.py,sha256=n0H8nHwQFfAeTwdJceJpi9VV1muYjJu_PjmzC_vrP84,5526
 fameio/input/scenario/attribute.py,sha256=pp9cquxfBUKNFwV3bTDBkDXv1k8ThBiAL6Eh-ag4kQk,11386
-fameio/input/scenario/contract.py,sha256=QPjsChndKMXphIpB_f0IeAiksZG7xz8U-xeLkvYRJUA,13211
+fameio/input/scenario/contract.py,sha256=fv4XRMMF8X9Q1LMNJsWcPfQx-EY40gDBWsEMJ7rsaBQ,15324
 fameio/input/scenario/exception.py,sha256=o64hd7FQrkTF6Ze075Cbt4TM3OkcyJFVSi4qexLuMoU,1939
 fameio/input/scenario/fameiofactory.py,sha256=HgLHVQGKsTPEFy8K1ILB7F_lJtHoMhu89inOgDWYP5k,2800
 fameio/input/scenario/generalproperties.py,sha256=C3ND-PLb1FrCRheIBIyxXHKsZVMW8GZVHUidyInqrOw,3749
@@ -48,13 +48,13 @@ fameio/scripts/make_config.py.license,sha256=EXKiZn-aoR7nO3auGMNGk9upHbobPLHAIBY
 fameio/scripts/reformat.py,sha256=jYJsl0UkXtZyn2GyA-QVAARilkHa_ZBWa5CGNIGNDuo,2850
 fameio/scripts/reformat.py.license,sha256=EXKiZn-aoR7nO3auGMNGk9upHbobPLHAIBYUO0S6LUg,107
 fameio/series.py,sha256=ipjDsDmgVlVzaYvXwXcWM8fpCy5w8hTNWTi4hPmvOuM,13654
-fameio/time.py,sha256=rJbcX304bjmZqmr7DozwZAvvNf4FCpxUYjUppl0BFb0,8431
+fameio/time.py,sha256=S8TagfGA7B44JPkj8YfC3ftkxODNTC6ZXELNQyHC1VA,10201
 fameio/tools.py,sha256=metmgKuZ0lubmTIPY3w_ertDxSLQtHIa6OlpcapyIk4,2478
-fameio-3.3.0.dist-info/entry_points.txt,sha256=IUbTceB_CLFOHulubEf9jgiCFsV2TchlzCssmjbiOKI,176
-fameio-3.3.0.dist-info/LICENSE.txt,sha256=eGHBZnhr9CWjE95SWjRfmhtK1lvVn5X4Fpf3KrrAZDg,10391
-fameio-3.3.0.dist-info/LICENSES/Apache-2.0.txt,sha256=eGHBZnhr9CWjE95SWjRfmhtK1lvVn5X4Fpf3KrrAZDg,10391
-fameio-3.3.0.dist-info/LICENSES/CC-BY-4.0.txt,sha256=y9WvMYKGt0ZW8UXf9QkZB8wj1tjJrQngKR7CSXeSukE,19051
-fameio-3.3.0.dist-info/LICENSES/CC0-1.0.txt,sha256=9Ofzc7m5lpUDN-jUGkopOcLZC3cl6brz1QhKInF60yg,7169
-fameio-3.3.0.dist-info/METADATA,sha256=10ZT26KgUXe2-ko_ZFfmqS2Z9eLTzim_9PST-aQwOHQ,41721
-fameio-3.3.0.dist-info/WHEEL,sha256=fGIA9gx4Qxk2KDKeNJCbOEwSrmLtjWCwzBz351GyrPQ,88
-fameio-3.3.0.dist-info/RECORD,,
+fameio-3.4.0.dist-info/entry_points.txt,sha256=IUbTceB_CLFOHulubEf9jgiCFsV2TchlzCssmjbiOKI,176
+fameio-3.4.0.dist-info/LICENSE.txt,sha256=eGHBZnhr9CWjE95SWjRfmhtK1lvVn5X4Fpf3KrrAZDg,10391
+fameio-3.4.0.dist-info/LICENSES/Apache-2.0.txt,sha256=eGHBZnhr9CWjE95SWjRfmhtK1lvVn5X4Fpf3KrrAZDg,10391
+fameio-3.4.0.dist-info/LICENSES/CC-BY-4.0.txt,sha256=y9WvMYKGt0ZW8UXf9QkZB8wj1tjJrQngKR7CSXeSukE,19051
+fameio-3.4.0.dist-info/LICENSES/CC0-1.0.txt,sha256=9Ofzc7m5lpUDN-jUGkopOcLZC3cl6brz1QhKInF60yg,7169
+fameio-3.4.0.dist-info/METADATA,sha256=qRURN8lvabRE9CmzKRuwsoi_1rKyv71TGkkdLJUAydE,42374
+fameio-3.4.0.dist-info/WHEEL,sha256=fGIA9gx4Qxk2KDKeNJCbOEwSrmLtjWCwzBz351GyrPQ,88
+fameio-3.4.0.dist-info/RECORD,,