fix docs for pip

Author: barajale

README.md

@@ -1,22 +1,14 @@
 
-## WEC-Grid: Integrating Wave Energy Converters into Power Grid Simulations
+# WEC-Grid: Integrating Wave Energy Converters into Power Grid Simulations
+
+<div style="clear: both; text-align: center;">
+  <img src="./docs/assets/WEC-Grid_mini_white.png" alt="WEC-Grid Logo" style="width: 80%; height: auto;">
+</div>
 
 **WEC-Grid** is an open-source Python library crafted to simulate the integration of Wave Energy Converters (WECs) power grid simulators like [PSS®E](https://new.siemens.com/global/en/products/energy/services/transmission-distribution-smart-grid/consulting-and-planning/pss-software/pss-e.html) & [PyPSA](https://pypsa.org/).
 
 **Documentation**: [acep-uaf.github.io/WEC-Grid](https://acep-uaf.github.io/WEC-Grid/)
 
-
-### Introduction
-
-<!-- Amidst the global shift towards sustainable energy solutions, Wave Energy Converters (WECs) emerge as groundbreaking innovations. These tools harbor the potential to tap into the energy reserves of our oceans. Yet, to weave them into intricate systems like microgrids, a profound modeling, testing, and analysis regimen is indispensable. WEC-Grid, presented through this Jupyter notebook, is a beacon of both demonstration and guidance, capitalizing on an open-source software to transcend these integration impediments. -->
-
-### Overview
-
-
-<!-- WEC-Grid is in its nascent stages, yet it presents a Python Jupyter Notebook that successfully establishes a PSSe API connection. It can solve both static AC & DC power flows, injecting data from a WEC device. Additionally, WEC-Grid comes equipped with rudimentary formatting tools for data analytics. The modular design ensures support for a selected power flow solving software and WEC devices.
-
-For the current implementations, WEC-Grid is compatible with PSSe and [WEC-SIM](https://wec-sim.github.io/WEC-Sim/). The widespread application of PSSe in the power systems industry, coupled with its robust API, makes it an ideal choice. -->
-
 ---
 
 ### Software Setup
@@ -78,3 +70,21 @@ For the current implementations, WEC-Grid is compatible with PSSe and [WEC-SIM](
    ```bash
    pytest -v
    ```
+
+---
+
+### Configuration
+
+You can configure paths via code or environment variables.
+
+- Database path
+  - Quick (env var): set `WECGRID_DB_PATH` to your SQLite database
+    - Windows (PowerShell): `$env:WECGRID_DB_PATH = "C:\\path\\to\\WECGrid.db"`
+    - macOS/Linux (bash/zsh): `export WECGRID_DB_PATH=~/path/to/WECGrid.db`
+  - Persistent (code): `engine.database.set_database_path("/path/to/WECGrid.db")`
+    - This writes a JSON config into your user config directory (e.g., `~/.wecgrid/database_config.json`).
+
+- WEC‑Sim path (MATLAB install)
+  - Quick (env var): set `WECGRID_WECSIM_PATH` to the WEC‑Sim folder
+  - Persistent (code): `engine.wecsim.set_wec_sim_path("/path/to/WEC-Sim")`
+    - Stored in your user config directory (e.g., `~/.wecgrid/wecsim_config.json`).

docs/wecgrid/database.md

@@ -220,13 +220,25 @@ from wecgrid import Engine
 # Initialize engine with database configuration
 engine = Engine()
 
-# First-time setup: configure database path
+# First-time setup: configure database path (persists to user config)
 engine.database.set_database_path(r"C:\path\to\WECGrid.db")
 
 # Or initialize new database with schema
 engine.database.initialize_database(r"C:\path\to\new_database.db")
 ```
 
+Alternatively, set an environment variable to point to the database (no code needed):
+
+```text
+# Windows PowerShell
+$env:WECGRID_DB_PATH = "C:\path\to\WECGrid.db"
+
+# macOS/Linux
+export WECGRID_DB_PATH=~/path/to/WECGrid.db
+```
+
+Note: WEC‑Grid stores persistent configuration in a user‑writable directory (e.g., `~/.wecgrid/`).
+
 ### Storing Simulation Results
 
 ```python
@@ -296,9 +308,9 @@ voltage_diff = abs(psse_buses['v_mag'] - pypsa_buses['v_mag'])
 - **Indexing**: Composite indexes optimize time-series query performance
 
 ### Configuration Management
-- **JSON Configuration**: Database path stored in `database_config.json`
-- **First-Time Setup**: User-guided configuration process
-- **Path Flexibility**: Support for absolute paths and relative workspace locations
+- **Environment Variable**: `WECGRID_DB_PATH` can set the database path
+- **User Config**: `database_config.json` stored in your user config dir (e.g., `~/.wecgrid/`)
+- **First-Time Setup**: User-guided configuration via `set_database_path()` or `initialize_database()`
 
 ---
 
@@ -365,4 +377,3 @@ recent_power = engine.database.query(
 - **[PSS®E Integration](psse.md)**: Commercial power system backend
 - **[PyPSA Integration](pypsa.md)**: Open-source power system backend
 - **[WEC Integration](wec.md)**: WEC farm and device data management
-

docs/wecgrid/wecsim.md

@@ -159,6 +159,18 @@ wecsim.set_wec_sim_path("/path/to/WEC-Sim")
 wecsim.show_config()  # Verify configuration
 ```
 
+Alternatively, configure via environment variable (overrides config file):
+
+```text
+# Windows PowerShell
+$env:WECGRID_WECSIM_PATH = "C:\\path\\to\\WEC-Sim"
+
+# macOS/Linux
+export WECGRID_WECSIM_PATH=~/path/to/WEC-Sim
+```
+
+WECSimRunner stores persistent configuration in a user‑writable directory (e.g., `~/.wecgrid/wecsim_config.json`).
+
 ### Model Directory Structure
 ```
 model_path/
@@ -212,4 +224,4 @@ wec_sim_id = wecsim(
 ### Performance Considerations
 - Reduce simulation length for testing workflows
 - Increase time step for faster execution (trade-off with accuracy)
-- Use smaller wave heights to avoid numerical instabilities
+- Use smaller wave heights to avoid numerical instabilities

src/wecgrid/modelers/wec_sim/runner.py

@@ -18,9 +18,24 @@
 # Local
 from wecgrid.util import WECGridDB
 
-# Configuration file path
-_CURR_DIR = os.path.dirname(os.path.abspath(__file__))
-_CONFIG_FILE = os.path.join(_CURR_DIR, "wecsim_config.json")
+from pathlib import Path
+
+
+def _user_config_dir() -> Path:
+    """Return a user-writable config directory for WEC-Grid.
+
+    Uses ``platformdirs`` if available, otherwise falls back to ``~/.wecgrid``.
+    """
+    try:
+        from platformdirs import user_config_dir  # type: ignore
+
+        return Path(user_config_dir(appname="wecgrid", appauthor=False))
+    except Exception:
+        return Path.home() / ".wecgrid"
+
+
+# Configuration file path (user-specific)
+_CONFIG_FILE = _user_config_dir() / "wecsim_config.json"
 
 
 class WECSimRunner:
@@ -58,18 +73,25 @@ def __init__(self, database: WECGridDB):
         self.matlab_engine = None
 
     def _load_config(self) -> None:
-        """Load WEC-Sim configuration from JSON file."""
+        """Load WEC-Sim configuration from env var or JSON file."""
+        # Highest priority: environment variable
+        env_path = os.getenv("WECGRID_WECSIM_PATH")
+        if env_path:
+            self.wec_sim_path = env_path
+            return
+
         try:
-            if os.path.exists(_CONFIG_FILE):
+            if _CONFIG_FILE.exists():
                 with open(_CONFIG_FILE, "r") as f:
                     config = json.load(f)
                     self.wec_sim_path = config.get("wec_sim_path")
         except Exception as e:
             print(f"Warning: Could not load WEC-Sim config: {e}")
 
     def _save_config(self) -> None:
-        """Save WEC-Sim configuration to JSON file."""
+        """Save WEC-Sim configuration to user JSON file."""
         try:
+            _CONFIG_FILE.parent.mkdir(parents=True, exist_ok=True)
             config = {"wec_sim_path": self.wec_sim_path}
             with open(_CONFIG_FILE, "w") as f:
                 json.dump(config, f, indent=2)
@@ -106,10 +128,11 @@ def show_config(self) -> None:
         Prints the currently configured WEC-Sim path along with the location of
         the configuration file used to persist this setting.
         """
-        print(f"WEC-Sim Configuration:")
+        print("WEC-Sim Configuration:")
         print(f"  Path: {self.wec_sim_path or 'Not configured'}")
         print(f"  Config file: {_CONFIG_FILE}")
-        print(f"  Config exists: {os.path.exists(_CONFIG_FILE)}")
+        print(f"  Config exists: {_CONFIG_FILE.exists()}")
+        print("  Env var: WECGRID_WECSIM_PATH (overrides config if set)")
 
     def start_matlab(self) -> bool:
         """Initialize MATLAB engine and configure WEC-Sim framework paths.

src/wecgrid/util/database.py

@@ -1,4 +1,10 @@
-"""Database utilities for WEC-Grid."""
+"""Database utilities for WEC-Grid.
+
+Configuration resolution order for database path:
+- Environment variable ``WECGRID_DB_PATH`` (if set)
+- User config file at ``<user-config>/wecgrid/database_config.json``
+- Otherwise, user is prompted to configure a path via API methods
+"""
 
 # Standard library
 import json
@@ -17,20 +23,44 @@
 import pandas as pd
 
 
+def _user_config_dir() -> Path:
+    """Return a user-writable config directory for WEC-Grid.
+
+    Uses ``platformdirs`` if available, otherwise falls back to ``~/.wecgrid``.
+    """
+    try:
+        from platformdirs import user_config_dir  # type: ignore
+
+        return Path(user_config_dir(appname="wecgrid", appauthor=False))
+    except Exception:
+        return Path.home() / ".wecgrid"
+
+
+def _db_config_file() -> Path:
+    return _user_config_dir() / "database_config.json"
+
+
 def get_database_config():
-    """Load database configuration from JSON file.
+    """Resolve database path from env var or user config file.
+
+    Resolution order:
+    1) ``WECGRID_DB_PATH`` environment variable
+    2) ``<user-config>/wecgrid/database_config.json``
 
     Returns:
-        str or None: Database path if found and valid, None otherwise.
+        str | None: Database path, or None if not configured.
     """
-    config_file = Path(__file__).parent / "database_config.json"
+    env_path = os.getenv("WECGRID_DB_PATH")
+    if env_path:
+        return str(Path(env_path).expanduser().absolute())
 
+    config_file = _db_config_file()
     if config_file.exists():
         try:
             with open(config_file, "r") as f:
                 config = json.load(f)
                 db_path = config.get("database_path")
-                if db_path and os.path.exists(db_path):
+                if db_path:
                     return str(Path(db_path).absolute())
         except (json.JSONDecodeError, KeyError) as e:
             print(f"Error reading database config: {e}")
@@ -39,14 +69,15 @@ def get_database_config():
 
 
 def save_database_config(db_path):
-    """Save database path to configuration file.
+    """Persist database path in user config directory.
 
     Args:
         db_path (str): Path to database file.
     """
-    config_file = Path(__file__).parent / "database_config.json"
+    cfg_dir = _user_config_dir()
+    cfg_dir.mkdir(parents=True, exist_ok=True)
+    config_file = _db_config_file()
     config = {"database_path": str(Path(db_path).absolute())}
-
     with open(config_file, "w") as f:
         json.dump(config, f, indent=2)
 
@@ -66,6 +97,10 @@ def _show_database_setup_message():
     print(
         '2. Create new database: engine.database.initialize_database(r"path/to/new_database.db")'
     )
+    print(
+        '3. Or set env var WECGRID_DB_PATH to point to your database file'
+    )
+    print(f"Config file (user): {_db_config_file()}\n")
     print("=" * 60 + "\n")