More improvements to dashboard and documentation

CITATION.cff

@@ -24,5 +24,5 @@ keywords:
   - data-science
   - Python
 license: GPL-3.0
-version: 3.1.0
+version: 3.2.0
 date-released: 2025-11-17

README.md

@@ -10,7 +10,7 @@ A Python package for [hill climbing](https://pubsonline.informs.org/doi/10.1287/
 
 ## 2. Features
 
-- **Flexible objectives**: Support for user supplied objective functions with custom multiple metrics
+- **Flexible objectives**: Support for user supplied objective functions with custom metrics
 - **Real-time monitoring dashboard**: Live progress plots and run info. with SQLite backend
 - **Replica exchange (parallel tempering)**: Replicas at different temperatures exchange configurations for improved global optimization (`multiprocessing.Pool`)
 - **Simulated annealing**: Temperature-based acceptance of suboptimal solutions to escape local minima

docs/source/_static/custom.css

@@ -31,11 +31,11 @@ html {
 
 /* Sidebar and navigation */
 .wy-side-nav-search {
-    background-color: #1a1a1a !important;
+    background-color: #34383C !important;
 }
 
 .wy-nav-side {
-    background-color: #2a2a2a !important;
+    background-color: #34383C !important;
 }
 
 /* Top navigation bar (breadcrumbs and page source) */
@@ -77,12 +77,15 @@ div[role="navigation"] hr,
 
 .wy-side-nav-search input[type=text] {
     border-color: #ff4b4b !important;
-    background-color: #2a2a2a !important;
-    color: #e0e0e0 !important;
+    background-color: #000000 !important;
+    color: #ffffff !important;
+    box-shadow: none !important;
 }
 
 .wy-side-nav-search input[type=text]:focus {
     border-color: #ff4b4b !important;
+    box-shadow: none !important;
+    outline: none !important;
 }
 
 .wy-menu-vertical a {
@@ -97,7 +100,7 @@ div[role="navigation"] hr,
 .wy-menu-vertical li.current a {
     color: #ff4b4b !important;
     border-right: solid 2px #ff4b4b !important;
-    background-color: #2a2a2a !important;
+    background-color: #34383C !important;
 }
 
 .wy-menu-vertical li.toctree-l1.current > a {
@@ -114,31 +117,31 @@ div[role="navigation"] hr,
     background-color: #3a3a3a !important;
 }
 
-/* Additional menu states to ensure no white backgrounds */
+/* Additional menu states to ensure consistent dark grey backgrounds */
 .wy-menu-vertical li.current {
-    background-color: #2a2a2a !important;
+    background-color: #34383C !important;
 }
 
 .wy-menu-vertical li.toctree-l1.current {
-    background-color: #2a2a2a !important;
+    background-color: #34383C !important;
 }
 
 .wy-menu-vertical li.toctree-l2 a,
 .wy-menu-vertical li.toctree-l3 a,
 .wy-menu-vertical li.toctree-l4 a {
-    background-color: #2a2a2a !important;
+    background-color: #34383C !important;
 }
 
 .wy-menu-vertical li.toctree-l2.current li.toctree-l3 {
-    background-color: #2a2a2a !important;
+    background-color: #34383C !important;
 }
 
 .wy-menu-vertical li ul li a {
-    background-color: #2a2a2a !important;
+    background-color: #34383C !important;
 }
 
 .wy-menu-vertical li ul {
-    background-color: #2a2a2a !important;
+    background-color: #34383C !important;
 }
 
 /* Sidebar caption (CONTENTS header) */
@@ -373,11 +376,33 @@ hr {
 
 /* Footer */
 .rst-footer-buttons {
-    border-top: 2px solid #ff4b4b !important;
+    border-top: none !important;
+    margin-bottom: 30px !important;
+}
+
+/* Hide the hr divider inside footer buttons and footer */
+.rst-footer-buttons hr,
+footer hr {
+    display: none !important;
+    visibility: hidden !important;
+    height: 0 !important;
+    margin: 0 !important;
+    padding: 0 !important;
+}
+
+/* Add a horizontal line at the end of content */
+.document::after {
+    content: "";
+    display: block;
+    height: 2px;
+    background-color: #ff4b4b;
+    margin-top: 30px;
+    margin-bottom: 30px;
 }
 
 footer {
     color: #cccccc !important;
+    margin-top: 30px !important;
 }
 
 footer span.commit code {

docs/source/advanced.rst

@@ -80,7 +80,7 @@ Choose the appropriate temperature range and spacing:
        data=data,
        objective_func=my_objective,
        n_replicas=8,
-       T_min=0.1,            # Coldest replica
+       T_min=0.0001,         # Coldest replica
        T_max=100.0,          # Hottest replica  
        temperature_scheme='geometric'  # Recommended for better mixing
    )
@@ -110,7 +110,7 @@ Different strategies for replica pairing:
        data=data,
        objective_func=my_objective,
        exchange_strategy='random',  # or 'even_odd', 'all_neighbors'
-       exchange_interval=10000  # Exchange attempts every 10000 steps
+       exchange_interval=100  # Exchange attempts every 100 steps
    )
 
 Choosing number of replicas

docs/source/conf.py

@@ -8,7 +8,7 @@
 project = 'Hill Climber'
 copyright = '2025, Hill Climber Contributors'
 author = 'Hill Climber Contributors'
-release = '3.1.0'
+release = '3.2.0'
 
 # -- General configuration ---------------------------------------------------
 extensions = [

docs/source/dashboard.rst

@@ -95,16 +95,21 @@ The database logging system uses an efficient collection and write strategy:
 - **Main process** performs all database writes after each batch, avoiding lock contention
 - No buffering needed - workers return collected metrics to main process
 
-db_enabled : bool, default=False
+db_enabled : bool, default=True
     Enable database logging for dashboard monitoring
 
 db_path : str, optional
-    Path to SQLite database file. Defaults to ``'data/hill_climber_progress.db'``
+    Path to SQLite database file. Defaults to ``'../data/hill_climb.db'``
 
 db_step_interval : int, optional
-    Collect metrics every Nth step. Default: ``exchange_interval // 10`` (10% sampling).
-    For small exchange intervals (≤10), defaults to 1 (every step). Must be less than
-    exchange_interval to ensure at least one collection per batch.
+    Collect metrics every Nth step. Uses tiered sampling based on exchange_interval:
+
+    - exchange_interval < 10: sample every step (1)
+    - exchange_interval 10-99: sample every 10 steps
+    - exchange_interval 100-999: sample every 100 steps  
+    - exchange_interval >= 1000: sample every 1000 steps
+
+    Must be less than or equal to exchange_interval to ensure at least one collection per batch.
 
 checkpoint_interval : int, default=1
     Number of batches between checkpoint saves. Default is 1 (checkpoint every batch).
@@ -122,14 +127,14 @@ Default settings (recommended)
    climber = HillClimber(
        data=data,
        objective_func=objective,
-       exchange_interval=10000,
+       exchange_interval=100,
        db_enabled=True,
-       # db_step_interval defaults to 10000 // 10 = 1000 (10% sampling)
+       # db_step_interval defaults to 100 (one sample per batch)
    )
 
 This provides good balance between resolution and performance:
 
-- Collects 1000 steps per replica per batch (10,000 / 10)
+- Collects 100 steps per replica per batch (100 / 1)
 - Main process writes all collected metrics once per batch
 - No worker I/O contention
 
@@ -141,27 +146,12 @@ Higher resolution (more database load)
    climber = HillClimber(
        data=data,
        objective_func=objective,
-       exchange_interval=10000,
+       exchange_interval=1000,
        db_enabled=True,
-       db_step_interval=500  # Collect every 500th step (5% sampling)
+       db_step_interval=100  # Collect every 100th step instead of default 1000
    )
 
-Collects 2000 steps per replica per batch (twice the default resolution).
-
-Lower resolution (faster, smaller database)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. code-block:: python
-
-   climber = HillClimber(
-       data=data,
-       objective_func=objective,
-       exchange_interval=10000,
-       db_enabled=True,
-       db_step_interval=2000  # Collect every 2000th step (20% sampling)
-   )
-
-Collects 500 steps per replica per batch (half the default, smaller database).
+Collects 10 samples per replica per batch instead of 1 (10x higher resolution).
 
 Database schema
 ---------------
@@ -268,7 +258,7 @@ Complete example
        objective_func=objective,
        max_time=30,
        n_replicas=4,
-       exchange_interval=10000,
+       exchange_interval=100,
        db_enabled=True,
        db_path='correlation_opt.db',
        checkpoint_file='correlation_opt.pkl',
@@ -322,23 +312,24 @@ Database size estimation
 
 With default settings:
 
-- ``exchange_interval=10000``
+- ``exchange_interval=100``
 - ``n_replicas=8``
 - 20 metrics
-- ``db_step_interval=1000`` (default: exchange_interval // 10)
+- ``db_step_interval=100`` (default: one sample per batch)
 
 Results in:
 
-- 1000 steps collected per replica per batch
-- 160,000 metric rows per batch
-- For 30-minute run (~100 batches): ~16M rows → 1-2GB database
+- 100 steps collected per replica per batch
+- 16,000 metric rows per batch
+- For 30-minute run (~1000 batches): ~16M rows → 1-2GB database
 
 To reduce size, increase ``db_step_interval``:
 
 .. code-block:: python
 
-   # Half the database size
-   db_step_interval = 2000  # 20% sampling instead of 10%
+   # For exchange_interval >= 1000, only 1 sample per batch by default
+   exchange_interval = 5000
+   # db_step_interval defaults to 1000 (one sample per 5 batches)
 
 See also
 --------

docs/source/index.rst

@@ -1,9 +1,9 @@
 Hill climber documentation
 ==========================
 
-A flexible simulated annealing optimizer for generating synthetic datasets with specific statistical properties.
+A flexible simulated annealing optimizer with replica exchange for generating synthetic datasets with specific properties (or whatever else you can dream up).
 
-**Hill Climber** is a Python package that uses simulated annealing to optimize datasets according to user-defined objective functions. It's particularly useful for:
+**Hill Climber** is a Python package to optimize datasets with user-defined objective functions. It's particularly useful for:
 
 - Generating synthetic data with specific statistical properties
 - Exploring relationships between different correlation measures

docs/source/installation.rst

@@ -36,7 +36,7 @@ No local setup required:
 2. Open in GitHub Codespaces
 3. The development environment will be configured automatically
 4. Documentation will be built and served at http://localhost:8000 automatically
-5. The monitoring dashboard will start and be served at http://localhost:8501 automatically
+5. The monitoring dashboard will start at http://localhost:8501 automatically
 
 Option 2: Local development
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -69,8 +69,8 @@ Clone and install locally:
 
       cd docs
       make html
-      # View docs by opening docs/build/html/index.html in a browser
-      # Or serve locally with: python -m http.server 8000 --directory build/html
+
+   View docs by opening docs/build/html/index.html in a browser or serve locally with: `python -m http.server 8000 --directory build/html`.
 
 5. Run tests to verify installation:
 
@@ -82,9 +82,6 @@ Clone and install locally:
       # Run specific test file
       python -m pytest tests/test_hill_climber.py
 
-      # Run with coverage
-      python -m pytest tests/ --cov=hill_climber
-
    All tests should pass.
 
 Verifying installation