WISDEM · RHammond2 · Mar 19, 2025 · Mar 3, 2025 · Mar 3, 2025 · Mar 3, 2025
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,53 +4,122 @@
 
 ### Features
 
-- Multiple instances of a servicing equipment can be created with a list of the name
-  and number of them in the following forms. This creates copies where the equipment's
-  name is suffixed with a 1-indexed indication of which number it is, such as
-  "Crew Transfer Vessel -1" through "Crew Transfer Vessel - 4" for the below example.
+#### Date-based maintenance and improved timing
+
+The frequency of maintenance events is now significantly more customizable by enabling
+custom starting dates and more resolved frequency inputs. There is no change required
+for existing configurations as the default value will `frequency` number of days until
+the next event.
+
+- `frequency` is an integer input (0 for unmodeled)
+- `frequency_basis` indicates the time basis for `frequency`, which is modeled in two
+  forms:
+  - timing based: amount of operational time that should pass before an event occurs,
+    which does not count downtime (repairs, upstream failure, or system offline) in the
+    time until the next event.
+    - "days": number of days between events (default)
+    - "months": number of months between events
+    - "years": number of years between events
+  - date based: uses a set schedule for when events should occur, regardless of downtime
+    and will use `start_date` as the first occurrence of the event.
+    - "date-days": number of days between events
+    - "date-months": number of months between events
+    - "date-years": number of years between events
+- `start_date`: The first occurrence of the maintenance event, which defaults to the
+  simulation start date + the expected interval. If the input is prior to the simulation
+  start date, then it is treated as a staggered timing, so, for instance, a biannual
+  event starting the year prior to the simulation ends up being staggered with the first
+  occurrence in the first year of the simulation, not the second. Similarly, this
+  allows for maintenance activities to start well into the simulation period allowing
+  for costs on OEM-warrantied maintenance activities to be unmodeled.
+
+A few examples of more complex scenarios assuming a 1/1/2000 simulation starting date:
+
+- Semiannual event to occur starting in the 3rd month of the simulation:
 
   ```yaml
-  ...
-  servicing_equipment:
-    - - ctv.yaml
-      - 4
-    - [hlv.yaml, 2]
-    - dsv.yaml
-  ...
+  frequency: 6
+  frequency_basis: months
+  start_date: "9/1/1999"
   ```
 
-- WOMBAT configurations now allow for the embedding of servicing equipment, turbine,
-  substation, cable, and port data within the main configuration. Now, the only files
-  required outside the primary configuration YAML are the weather profile and layout.
-  To utilize this update, data can be included in the following form:
+- Summer-based annual event with the first occurrence in the 3rd year of the simulation:
 
   ```yaml
-  servicing_equipment:
-    - [7, ctv]
-  ...  # Other configuration details
-  vessels:
-    ctv:
-      ...  # Contents of library/corewind/vessels/ctv.yaml
-  turbines:
-    corewind_15MW:
-      ...  # Contents of library/corewind/turbines/corewind_15MW.yaml
-  substations:
-    corewind_substation:
-      ...  # Contents of library/corewind/substations/corewind_substation.yaml
-  cables:
-    corewind_array:
-      ...  # Contents of library/corewind/cables/corewind_array.yaml
-    corewind_export:
-      ...  # Contents of library/corewind/cables/corewind_export.yaml
+  frequency: 1
+  frequency_basis: years
+  start_date: "6/1/2003"
   ```
 
+- Annual, June maintenance activity:
+
+  ```yaml
+  frequency: 1
+  frequency_basis: "date-years"
+  start_date: "6/1/2000"
+  ```
+
+- Biannual, June maintenance activity that should start in the first year, and every
+  other year after that:
+
+  ```yaml
+  frequency: 1
+  frequency_basis: "date-years"
+  start_date: "6/1/2000"
+  ```
+
+#### Repeat vessel configuration simplification
+
+Multiple instances of a servicing equipment can be created with a list of the name
+and number of them in the following forms. This creates copies where the equipment's
+name is suffixed with a 1-indexed indication of which number it is, such as
+"Crew Transfer Vessel -1" through "Crew Transfer Vessel - 4" for the below example.
+
+```yaml
+...
+servicing_equipment:
+  - - ctv.yaml
+    - 4
+  - [hlv.yaml, 2]
+  - dsv.yaml
+...
+```
+
+#### Single(ish) file configuration
+
+WOMBAT configurations now allow for the embedding of servicing equipment, turbine,
+substation, cable, and port data within the main configuration. Now, the only files
+required outside the primary configuration YAML are the weather profile and layout.
+To utilize this update, data can be included in the following form:
+
+```yaml
+servicing_equipment:
+  - [7, ctv]
+...  # Other configuration details
+vessels:
+  ctv:
+    ...  # Contents of library/corewind/vessels/ctv.yaml
+turbines:
+  corewind_15MW:
+    ...  # Contents of library/corewind/turbines/corewind_15MW.yaml
+substations:
+  corewind_substation:
+    ...  # Contents of library/corewind/substations/corewind_substation.yaml
+cables:
+  corewind_array:
+    ...  # Contents of library/corewind/cables/corewind_array.yaml
+  corewind_export:
+    ...  # Contents of library/corewind/cables/corewind_export.yaml
+```
+
 ### Updates
 
 - Adds a CI check for code linting (pre-commit) and for the documentation building.
 - Updates the minimum Python version to 3.10.
 - Basic tests added for the Simulation API
 - The wind farm operation level calculation was moved to `wombat/utilities/utilities.py`
   so it can be reused when `Metrics` loads the operational data.
+- Fixes the `FutureWarnings` from Pandas about changing offset strings.
 
 ## 0.9.7 (12 February 2025)
 

diff --git a/docs/API/types.md b/docs/API/types.md
@@ -1,5 +1,5 @@
 (types)=
-# Data Classes
+# Conifgurations (Data Classes)
 
 The WOMBAT architecture relies heavily on a base set of data classes to process most of
 the model's inputs. This enables a rigid, yet robust data model to properly define a
@@ -36,7 +36,8 @@ hoping for the best.
    :members:
    :undoc-members:
    :exclude-members: time, materials, frequency, equipment, system_value, description,
-    level, operation_reduction, rng, service_equipment, replacement
+    level, operation_reduction, rng, service_equipment, replacement, frequency_basis,
+    start_date, request_id, event_dates
 ```
 
 (types:maintenance:unscheduled)=
@@ -48,7 +49,7 @@ hoping for the best.
    :undoc-members:
    :exclude-members: scale, shape, time, materials, operation_reduction, weibull, name,
     maintenance, failures, level, equipment, system_value, description, rng,
-    service_equipment, replacement
+    service_equipment, replacement, request_id
 ```
 
 (types:maintenance:requests)=

diff --git a/docs/examples/how_to.md b/docs/examples/how_to.md
@@ -543,6 +543,52 @@ project_capacity: 240
 #                          pointer is provided here and located in: dinwoodie / project / port
 ```
 
+```{note}
+As of v0.10, multiple vessels can be modeled with a single configuration, and vessel,
+turbine, cable, and substation configurations can be included directly in the contents
+of the primary configuration.
+```
+
+Alternatively, the configuration can be simplified to be of the following form to utilize
+repeated vessel configurations and the single file configuration. The new keys for where
+to embed the data directly correspond to the folder names where the files originally
+resided. For instance, below embedding `<library>/vessels/ctv.yaml` into the
+main configuration means that we need a new key called `vessels`, with a subkey
+underneath called `ctv`.
+
+```{code-block} yaml
+name: dinwoodie_base
+weather: alpha_ventus_weather_2002_2014.csv  # located in: dinwoodie / weather
+service_equipment:
+# YAML-encoded list, but could also be created in standard Python list notation with
+# square brackets: [ctv1.yaml, ctv2.yaml, ..., hlv_requests.yaml]
+# All below equipment configurations are located in: dinwoodie / vessels
+  - [ctv, 3]
+  - fsv_requests.yaml
+  - hlv_requests.yaml
+layout: layout.csv  # located in: dinwoodie / windfarm
+inflation_rate: 0
+fixed_costs: fixed_costs.yaml  # located in: dinwoodie / project / config
+workday_start: 7
+workday_end: 19
+start_year: 2003
+end_year: 2012
+project_capacity: 240
+vessels:
+  ctv:
+    ... # contents of ctv1.yaml without the numbered naming which is created automatically
+turbines:
+  ...
+cables:
+  ...
+substations:
+  ...
+```
+
+For a complete example of this, please see the
+`library/corewind/project/config/morro_bay_in_situ_consolidated.yaml` configuration
+file.
+
 ## Create a simulation
 
 There are two ways that this could be done, the first is to use the classmethod
@@ -627,7 +673,6 @@ timing = end - start
 print(f"Run time: {timing / 60:,.2f} minutes")
 ```
 
-
 ## Metric computation
 
 For a more complete view of what metrics can be compiled, please see the [metrics notebook](metrics_demonstration.md), though for the sake of demonstration a few methods will

diff --git a/docs/examples/index.md b/docs/examples/index.md
@@ -55,7 +55,7 @@ events. The following will break down the differences between each of these syst
 modeling assumptions as well as the basic operations of the maintenance and failure models.
 
 - Maintenance
-  - `frequency`: based on a fixed number of days between an event
+  - `frequency`: based on an amount of time between events and a given starting date.
   - `operation_reduction`: the percentage of degradation the triggering of this event
     cause
 - Failure

diff --git a/pyproject.toml b/pyproject.toml
@@ -27,6 +27,7 @@ dependencies = [
     "types-typed-ast>=1.5",
     "types-PyYAML>=6",
     "types-python-dateutil>=2.8",
+    "python-dateutil",
 ]
 keywords = [
     "python3",

diff --git a/tests/test_cable.py b/tests/test_cable.py
@@ -86,8 +86,9 @@ def test_cable_failures(env_setup):
     # for p in cable.processes.values():
     #     pprint(p._target.__dict__)
     assert getattr(list(cable.processes.values())[0]._target, "_delay", None) is None
-    assert getattr(list(cable.processes.values())[1]._target, "_delay", None) == (
-        1416 - catastrophic_timeout
+    assert (
+        getattr(list(cable.processes.values())[1]._target, "_delay", None)
+        == env.max_run_time - catastrophic_timeout
     )
 
     # Check the failure was submitted and no other items exist for this cable