minor changes

Author: barajale

docs/data/wec-models.md

@@ -26,9 +26,19 @@ WEC-Grid includes two pre-configured wave energy converter models for simulation
 
 ## Wave-to-Wire Model Architecture 
 
-<div style="clear: both; text-align: center;">
-  <img src="../../assets/lupa_simulink.png" alt="Wave-to-Wire" style="width: 100%; height: auto;">
-</div>
+### Wave-to-Wire Model Architecture
+
+<!-- <div style="clear: both; text-align: center;">
+  <img src="../../assets/lupa_simulink.png" alt="LUPA Wave-to-Wire Model Architecture" style="width: 100%; height: auto;">
+  <p style="font-style: italic; margin-top: 8px; color: #666;">
+    Figure 1: Complete wave-to-wire model architecture showing the integration of WEC-Sim hydrodynamic simulation with power take-off systems, electrical conversion, and grid interface components.
+  </p>
+</div> -->
+
+<figure markdown="span">
+  ![LUPA Wave-to-Wire Model Architecture](../../assets/lupa_simulink.png){ width="300" }
+  <figcaption>Complete wave-to-wire model architecture showing the integration of WEC-Sim hydrodynamic simulation with power take-off systems, electrical conversion, and grid interface components.</figcaption>
+</figure>
 
 
 In the available models below we have a custom Wave-to-Wire model that captures the full energy conversion chain from ocean waves to grid-delivered electricity.  

docs/wecgrid/plot.md

@@ -66,13 +66,25 @@ fig, ax = engine.plot.gen(software="pypsa", parameter="p", gen=["WEC_Farm_1"])
 ```python
 # Compare PSS®E vs PyPSA bus voltages
 plotter = WECGridPlot(engine)
-fig, ax, metrics = plotter.compare_modelers(
+fig, ax = plotter.compare_modelers(
     grid_component="bus",
     name=["Bus_1", "Bus_5"],
     parameter="v_mag",
-    annotate=True,         # overlay metrics on figure
+    # annotate=False,      # default: do not overlay metrics on figure
     print_metrics=True,    # print metrics to console
 )
+```
+
+To get only the metrics DataFrame (and skip showing the figure):
+
+```python
+metrics = plotter.compare_modelers(
+    grid_component="bus",
+    name=["Bus_1", "Bus_5"],
+    parameter="v_mag",
+    dataframe=True,        # return DataFrame, do not show plot
+    print_metrics=False,   # optional: silence console output
+)
 print(metrics)
 ```
 

docs/wecgrid/wecsim.md

@@ -61,7 +61,7 @@ MATLAB Engine → Model Directory → Set Parameters → w2gSim() → Results 
     - `set_wec_sim_path()` — Configure WEC-Sim installation location
 
 - **Simulation Control**
-    - `__call__()` — Execute complete WEC device simulation with parameters
+    - `simulate()` — Execute complete WEC device simulation with parameters
     - Wave parameters: height [m], period [s], spectrum type, random seed
     - Simulation parameters: duration [s], time step [s], model path
 
@@ -225,3 +225,125 @@ wec_sim_id = wecsim(
 - Reduce simulation length for testing workflows
 - Increase time step for faster execution (trade-off with accuracy)
 - Use smaller wave heights to avoid numerical instabilities
+
+### Example Run
+
+elow is an example of running a full 24 wec simulation of the RM3 wave energy model.
+
+# Run WEC-Sim simulation of the RM3 wave energy model 
+
+```python 
+
+runner.wecsim(
+    model_path="./wec/RM3",
+    sim_length=3600 * 24,  # 24 hours in seconds
+    delta_time=0.1,
+    spectrum_type='PM',
+    wave_class='irregular',
+    wave_height=2.5,
+    wave_period=8.0,
+    wave_seed = random.randint(1, 100),
+)
+
+```
+```bash
+
+⠀              WEC-SIM⠀⠀⠀⠀     ⣠⣴⣶⠾⠿⠿⠯⣷⣄⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
+            ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣼⣾⠛⠁⠀⠀⠀⠀⠀⠀⠈⢻⣦⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
+            ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣠⣾⠿⠁⠀⠀⠀⢀⣤⣾⣟⣛⣛⣶⣬⣿⣆⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
+            ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣾⠟⠃⠀⠀⠀⠀⠀⣾⣿⠟⠉⠉⠉⠉⠛⠿⠟⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
+            ⠀⠀⠀⠀⠀⠀⠀⠀⢀⣴⡟⠋⠀⠀⠀⠀⠀⠀⠀⣿⡏⣤⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
+            ⠀⠀⠀⠀⠀⠀⠀⣠⡿⠛⠀⠀⠀⠀⠀⠀⠀⠀⠀⠙⣷⡍⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣀⣀⣤⣤⣤⣀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
+            ⠀⠀⠀⠀⠀⣠⣼⡏⠀⠀           ⠈⠙⠷⣤⣤⣠⣤⣤⡤⡶⣶⢿⠟⠹⠿⠄⣿⣿⠏⠀⣀⣤⡦⠀⠀⠀⠀⣀⡄
+            ⢀⣄⣠⣶⣿⠏⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠉⠓⠚⠋⠉⠀⠀⠀⠀⠀⠀⠈⠛⡛⡻⠿⠿⠙⠓⢒⣺⡿⠋⠁
+            ⠉⠉⠉⠛⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠉⠉⠁⠀
+            
+Starting MATLAB Engine... MATLAB engine started.
+Adding WEC-SIM to path... WEC-SIM path added.
+Starting WEC-SIM simulation...
+	 Model: RM3
+	 Model Path: ./wec/RM3
+	 Simulation Length: 86400 seconds
+	 Time Step: 0.1 seconds
+	 Wave class: irregular
+	 Wave Height: 2.5 m
+	 Wave Period: 8.0 s
+
+simulation complete... writing to database at 
+	c:\Users\alexb\research\WEC-GRID\examples\WECGrid.db
+WEC-SIM complete: model = RM3, wec_sim_id = 1, duration = 86400s
+MATLAB Output:
+==========
+WEC-Sim: An open-source code for simulating wave energy converters
+Version: 5.0.1
+
+Initializing the Simulation Class...
+	Case Dir: C:\Users\alexb\research\WEC-GRID\examples\wec\RM3 
+
+WEC-Sim Input From Standard wecSimInputFile.m Of Case Directory... 
+WEC-Sim: An open-source code for simulating wave energy converters
+Version: 5.0.1
+
+Initializing the Simulation Class...
+	Case Dir: C:\Users\alexb\research\WEC-GRID\examples\wec\RM3 
+Elapsed time is 0.399332 seconds.
+
+WEC-Sim Pre-processing ...   
+	Infinite water depth specified in BEM and "waves.waterDepth" not specified in input file.
+Set water depth to 200m for visualization.
+Elapsed time is 24.918356 seconds.
+
+WEC-Sim Simulation Settings:
+	Start Time                     (sec) = 0
+	End Time                       (sec) = 86400
+	Time Step Size                 (sec) = 0.1
+	Ramp Function Time             (sec) = 0
+	Convolution Integral Interval  (sec) = 60
+	 Number of Time Steps     = 864000 
+
+Wave Environment: 
+	Wave Type                            = Irregular Waves (Predefined Random Phase)
+	Spectrum Type                        = Pierson-Moskowitz  
+	Significant Wave Height, Hs      (m) = 2.5
+	Peak Wave Period, Tp           (sec) = 8
+
+List of Body: Number of Bodies = 2 
+
+	***** Body Number 1, Name: float *****
+	Body CG                          (m) = [0,0,-0.72]
+	Body Mass                       (kg) = 725834 
+	Body Diagonal MOI              (kgm2)= [2.09073E+07,2.13061E+07,3.70855E+07]
+
+	***** Body Number 2, Name: spar *****
+	Body CG                          (m) = [0,0,-21.29]
+	Body Mass                       (kg) = 886691 
+	Body Diagonal MOI              (kgm2)= [9.44196E+07,9.44071E+07,2.85422E+07]
+
+List of PTO(s): Number of PTOs = 1 
+
+	***** PTO Name: PTO1 *****
+	PTO Stiffness           (N/m;Nm/rad) = 0
+	PTO Damping           (Ns/m;Nsm/rad) = 0
+
+List of Constraint(s): Number of Constraints = 1 
+
+	***** Constraint Name: Constraint1 *****
+
+
+Simulating the WEC device defined in the SimMechanics model C:\Users\alexb\research\WEC-GRID\examples\wec\RM3\W2G_ss_RM3.slx...   
+Elapsed time is 5.154023 seconds.
+Elapsed time is 802.377574 seconds.
+
+Post-processing and saving...   
+Elapsed time is 8.199315 seconds.
+Inserting simulation metadata...
+  model_type: RM3 (class: char)
+  wave_spectrum: PM (class: char)
+  wave_class: irregular (class: char)
+  sim_hash: RM3_2.5m_8.0s_94 (class: char)
+WEC-Sim data stored: wec_sim_id = 1, 864001 time points
+
+==========
+MATLAB engine stopped.
+
+```

src/wecgrid/modelers/wec_sim/runner.py

@@ -254,7 +254,7 @@ def sim_results(self, df_power, model, wec_sim_id):
 
         plt.show()
 
-    def __call__(
+    def simulate(
         self,
         model_path: str,
         sim_length: int = 3600 * 24,  # 24 hours

src/wecgrid/util/plot.py

@@ -671,7 +671,8 @@ def compare_modelers(
         grid_component: str,
         name: List[str],
         parameter: str,
-        annotate: bool = True,
+        annotate: bool = False,
+        dataframe: bool = False,
         print_metrics: bool = True,
     ):
         """Compare a component parameter across PSS®E and PyPSA.
@@ -681,13 +682,15 @@ def compare_modelers(
             name: Component name(s) to compare.
             parameter: Parameter to compare (e.g., "p", "v_mag").
             annotate: If True, overlay metrics text on the figure.
+            dataframe: If True, return only a metrics DataFrame and do not show the plot.
             print_metrics: If True, print metrics to stdout.
 
         Returns:
-            (Figure, Axes, DataFrame): Matplotlib figure/axes and a DataFrame
-            with columns ["component", "rmse", "mae", "max_abs_err",
-            "mape_pct", "nrmse_mean", "nrmse_range", "r", "n"]. The
-            DataFrame is None if metrics cannot be computed.
+            - If `dataframe` is False (default): `(Figure, Axes)` for the comparison plot.
+            - If `dataframe` is True: a pandas `DataFrame` with columns
+              ["component", "rmse", "mae", "max_abs_err", "mape_pct",
+              "nrmse_mean", "nrmse_range", "r", "n"]. Returns `None` if
+              metrics cannot be computed.
         """
         # Check for available software data
         available_software = []
@@ -701,7 +704,7 @@ def compare_modelers(
                 f"Available: {available_software}. Use add_grid() to add GridState objects "
                 f"or ensure both 'psse' and 'pypsa' are loaded in the engine."
             )
-            return None, None, None
+            return None if dataframe else (None, None)
 
         fig, ax = plt.subplots(figsize=(12, 6))
 
@@ -890,8 +893,12 @@ def compare_modelers(
                     s1 = df_psse[col]
                     s2 = df_pypsa[col]
                     mask = s1.notna() & s2.notna()
-                    s1v = s1[mask].values
-                    s2v = s2[mask].values
+                    # Coerce to numeric and drop any non-numeric remnants
+                    s1c = pd.to_numeric(s1[mask], errors="coerce")
+                    s2c = pd.to_numeric(s2[mask], errors="coerce")
+                    mask2 = s1c.notna() & s2c.notna()
+                    s1v = s1c[mask2].to_numpy(dtype=float).ravel()
+                    s2v = s2c[mask2].to_numpy(dtype=float).ravel()
                     if len(s1v) == 0:
                         rmse = np.nan
                         mae = np.nan
@@ -924,10 +931,19 @@ def compare_modelers(
                             mape_pct = float(100.0 * np.mean(np.abs(err[nonzero] / s1v[nonzero])))
                         else:
                             mape_pct = np.nan
-                        if len(s1v) < 2 or np.std(s1v) == 0 or np.std(s2v) == 0:
+                        # Pearson correlation (manual) with ddof=1
+                        if len(s1v) < 2:
                             corr = np.nan
                         else:
-                            corr = float(np.corrcoef(s1v, s2v)[0, 1])
+                            sx = float(np.std(s1v, ddof=1))
+                            sy = float(np.std(s2v, ddof=1))
+                            if sx <= eps or sy <= eps:
+                                corr = np.nan
+                            else:
+                                xm = float(np.mean(s1v))
+                                ym = float(np.mean(s2v))
+                                cov = float(np.sum((s1v - xm) * (s2v - ym)) / (len(s1v) - 1))
+                                corr = float(cov / (sx * sy))
                         n = int(len(s1v))
 
                     # Prefer PSSE friendly name, then PYPSA, else the key
@@ -1008,5 +1024,10 @@ def compare_modelers(
             pass  # Fall back to default formatting if anything goes wrong
 
         plt.tight_layout()
-        plt.show()
-        return fig, ax, metrics_df
+        # Return depending on 'dataframe' flag
+        if dataframe:
+            # Do not display the figure when only metrics are requested
+            return metrics_df
+        else:
+            plt.show()
+            return fig, ax