ROSE Spec for Service

_typos.toml

@@ -0,0 +1,3 @@
+[default.extend-words]
+# "aas" appears in rose-aas.md / "ROSE as a Service" links — not a typo of "as"/"ass".
+aas = "aas"

docs/getting-started/faq.md

@@ -9,6 +9,9 @@ Refer to the [Installation Guide](installation.md) for detailed instructions bas
 A dry run allows you to simulate the execution of your tasks locally without making any changes to the behavior of your ML workflow.
 It's a way to verify your setup is working on HPC before applying it to prevent time and resource waste.
 
+!!! tip
+    See the [Dry Run](dry-run.md) guide for a full step-by-step walkthrough.
+
 ## Q3: What if I have an issue?
 If you have any additional questions or an issue, feel free to reach out to our support team by opening a Github [ticket](https://github.com/radical-cybertools/ROSE/issues).
 

docs/getting-started/installation.md

@@ -7,7 +7,7 @@ machines, please refer to the following link: [RADICAL-Pilot Supported HPC Machi
 ## For Linux and macOS 🐧
 
 1. Clone the latest version from the [official website](https://github.com/radical-cybertools/ROSE).
-   ```
+   ```bash
    git clone https://github.com/radical-cybertools/ROSE.git
    ```
 2. Run the following commands to install ROSE and its dependencies:
@@ -21,19 +21,19 @@ machines, please refer to the following link: [RADICAL-Pilot Supported HPC Machi
 1. Download the Windows WSL installer from the [official website](https://apps.microsoft.com/detail/9pdxgncfsczv?hl=en-US&gl=US).
 2. Setup you WSL user name and password.
 3. Make sure you have Python 3.9 or higher in your WSL as follows:
-    ```
+    ```bash
     python --version
     ```
 4. create new pip virtual env:
-    ```
+    ```bash
     python3 -m venv rose_env
     ```
 5. Activate the env:
-   ```
+   ```bash
    source rose_env/bin/activate
    ```
 6. Clone the latest version from the [official website](https://github.com/radical-cybertools/ROSE).
-   ```
+   ```bash
    git clone https://github.com/radical-cybertools/ROSE.git
    ```
 7. Run the following commands to install ROSE and its dependencies:
@@ -42,4 +42,5 @@ machines, please refer to the following link: [RADICAL-Pilot Supported HPC Machi
     pip install .
     ```
 
-If you encounter any issues, refer to the [Issues Section](https://github.com/radical-cybertools/ROSE/issues).
+!!! note
+    If you encounter any issues, refer to the [Issues Section](https://github.com/radical-cybertools/ROSE/issues).

docs/index.md

@@ -1,6 +1,6 @@
 ## What is ROSE? 🌹
 
-ROSE: RADICAL Orchestrator for Surrogate Exploration (ROSE) toolkit is a framework designed to enable the concurrent and adaptive execution of simulation, surrogate training, and selection tasks on High-Performance Computing (HPC) resources. ROSE is a Python package that provides tools for developing active and reinforcement learning (AL and RL) methods for scientific applications. It enables users to define simulation and surrogate training tasks and automatically manage their execution on HPC resources via a predefined set of Learning Policies (Learners).
+ROSE: RADICAL Orchestrator for Surrogate Exploration (ROSE) toolkit is a framework designed to enable the distributed, concurrent and adaptive execution of simulation, surrogate training, and selection tasks on High-Performance Computing (HPC) resources at a scale. ROSE is a Python package that provides tools for developing active and reinforcement learning (AL and RL) methods for scientific applications. It enables users to define simulation and surrogate training tasks and automatically manage their execution on HPC resources via a predefined set of Learning Policies (Learners).
 
 ROSE also includes tools to facilitate the selection of the most effective surrogate model for a given simulation based on performance metrics.
 
@@ -9,7 +9,7 @@ ROSE leverages [**RADICAL-Cybertools**](https://radical-cybertools.github.io), a
 
 ## Why ROSE? 🚀🚀🚀
 ROSE allows you to enable, scale, and accelerate your learning workflows across thousands of CPU cores and GPUs effectively and efficiently with just a few lines of code.
-ROSE is built on the [**RADICAL-AsyncFlow**](https://radical-cybertools.github.io/radical.asyncflow/) and [**RADICAL-Pilot**](https://github.com/radical-cybertools/radical.pilot) runtime system, a powerful execution engine that enables the distributed execution of millions of scientific tasks and applications such as executables, functions and containers effortlessly.
+ROSE is built on the [**RADICAL-AsyncFlow**](https://radical-cybertools.github.io/radical.asyncflow/) and [**RHAPSODY**](https://radical-cybertools.github.io/rhapsody/landing.html) runtime system, a powerful execution engine that enables the distributed execution of millions of scientific tasks and applications such as executables, functions and containers effortlessly.
 
 **Preemption-safe on HPC.** Every completed iteration is written to disk before the next one starts. If the job is killed mid-run, all completed iterations are already on disk — inspect them, resume from the last checkpoint, and never rerun a finished iteration.
 

docs/integrations/clearml.md

@@ -61,6 +61,10 @@ For **parallel learners**, `state.learner_id` is included automatically. The tra
 each state as a separate `series` inside the same scalar title, making per-learner curves
 directly comparable without any user code.
 
+!!! note
+    No user code is required to get this overlay — `state.learner_id` is already populated
+    by the parallel learner framework before the tracker ever sees the state.
+
 ### Task tags — logged in `on_stop`
 
 | ClearML tag | Value |

docs/scripts/custom.js

@@ -0,0 +1,38 @@
+// ROSE docs — subtle scroll-reveal for a more fluid reading experience.
+// Pairs with the .rose-reveal / .rose-revealed rules in styles/custom.css.
+(() => {
+  const reduceMotion = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+  if (reduceMotion || !("IntersectionObserver" in window)) return;
+
+  const SELECTOR =
+    ".md-content__inner > h2, .md-content__inner > h3, .md-content__inner > p, " +
+    ".md-content__inner > table, .md-content__inner > .admonition, " +
+    ".md-content__inner > pre, .md-content__inner > .highlight";
+
+  const observer = new IntersectionObserver(
+    (entries) => {
+      entries.forEach((entry) => {
+        if (entry.isIntersecting) {
+          entry.target.classList.add("rose-revealed");
+          observer.unobserve(entry.target);
+        }
+      });
+    },
+    { threshold: 0.05, rootMargin: "0px 0px -40px 0px" }
+  );
+
+  const observe = () => {
+    document.querySelectorAll(SELECTOR).forEach((el) => {
+      el.classList.add("rose-reveal");
+      observer.observe(el);
+    });
+  };
+
+  // mkdocs-material's instant navigation swaps content without a full page
+  // load, so re-run on each page change via its document$ observable.
+  if (typeof document$ !== "undefined") {
+    document$.subscribe(observe);
+  } else {
+    document.addEventListener("DOMContentLoaded", observe);
+  }
+})();

docs/styles/custom.css

@@ -1,15 +1,186 @@
-/* Change the banner background color to dark rose */
+/* ============================================================
+   ROSE docs — fluid theme refinement
+   Cohesive rose/pink brand palette, softened rounded surfaces,
+   smooth motion, and viewport-responsive (fluid) type & spacing.
+   ============================================================ */
+
+/* ---- 1. Brand palette --------------------------------------- */
+:root {
+  --rose-50:  #fdf2f6;
+  --rose-100: #fbe4ee;
+  --rose-300: #f06ea6;
+  --rose-500: #d81b60;
+  --rose-600: #c2185b;
+  --rose-700: #a3134c;
+  --rose-900: #6e0e35;
+
+  --md-primary-fg-color:             var(--rose-600);
+  --md-primary-fg-color--light:      var(--rose-300);
+  --md-primary-fg-color--dark:       var(--rose-900);
+  --md-accent-fg-color:              var(--rose-500);
+  --md-accent-fg-color--transparent: rgba(216, 27, 96, 0.1);
+
+  --rose-radius:       0.6rem;
+  --rose-radius-lg:    1rem;
+  --rose-shadow:       0 2px 10px rgba(194, 24, 91, 0.08), 0 1px 2px rgba(0, 0, 0, 0.04);
+  --rose-shadow-hover: 0 6px 20px rgba(194, 24, 91, 0.16), 0 2px 4px rgba(0, 0, 0, 0.06);
+  --rose-transition:   180ms cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+[data-md-color-scheme="slate"] {
+  --md-primary-fg-color:        var(--rose-700);
+  --md-primary-fg-color--dark:  #4a0a26;
+  --md-accent-fg-color:         var(--rose-300);
+  --rose-shadow:       0 2px 12px rgba(0, 0, 0, 0.35);
+  --rose-shadow-hover: 0 8px 24px rgba(0, 0, 0, 0.45);
+}
+
+/* ---- 2. Fluid typography & layout ----------------------------- */
+html {
+  font-size: clamp(18px, 0.6vw + 16px, 22px);
+  scroll-behavior: smooth;
+}
+
+.md-typeset h1 { font-size: clamp(1.8rem, 1.2rem + 1.6vw, 2.6rem); }
+.md-typeset h2 { font-size: clamp(1.4rem, 1.1rem + 1vw, 2rem); }
+.md-typeset h3 { font-size: clamp(1.15rem, 1rem + 0.5vw, 1.5rem); }
+
+.md-typeset {
+  line-height: 1.65;
+}
+
+.md-content__inner {
+  padding: clamp(0.8rem, 1vw + 0.5rem, 1.8rem) clamp(0.6rem, 2vw, 2rem);
+}
+
+.md-grid {
+  max-width: clamp(960px, 90vw, 1440px);
+}
+
+/* ---- 3. Header & tabs: subtle gradient instead of flat fill --- */
 .md-header {
-  background-color: #c2185b !important; /* Dark rose color */
+  background: linear-gradient(135deg, var(--rose-600), var(--rose-700));
+  box-shadow: 0 2px 12px rgba(194, 24, 91, 0.25);
+  transition: box-shadow var(--rose-transition), transform var(--rose-transition);
+}
+
+.md-tabs {
+  background: linear-gradient(135deg, var(--rose-700), var(--rose-900));
+}
+
+/* ---- 4. Motion: links, nav, tabs ------------------------------ */
+a,
+.md-nav__link,
+.md-tabs__link,
+.md-typeset a {
+  transition: color var(--rose-transition), background-color var(--rose-transition),
+    opacity var(--rose-transition);
 }
 
-/* Ensure the active navigation link is distinct */
 .md-nav__link--active {
-  color: #c2185b !important; /* Slightly darker black for active link */
-  font-weight: bold;
+  color: var(--rose-600) !important;
+  font-weight: 600;
+}
+
+[data-md-color-scheme="slate"] .md-nav__link--active {
+  color: var(--rose-300) !important;
+}
+
+.md-nav__link:hover {
+  opacity: 0.75;
 }
 
+.md-typeset a:hover {
+  text-decoration: underline;
+}
+
+/* ---- 5. Softened, elevated surfaces ---------------------------- */
+.md-typeset .admonition,
+.md-typeset details {
+  border-radius: var(--rose-radius);
+  box-shadow: var(--rose-shadow);
+  border-width: 0;
+  border-left: 4px solid var(--md-accent-fg-color);
+  overflow: hidden;
+  transition: box-shadow var(--rose-transition);
+}
+
+.md-typeset .admonition:hover,
+.md-typeset details:hover {
+  box-shadow: var(--rose-shadow-hover);
+}
+
+.md-typeset pre,
+.md-typeset .highlight {
+  border-radius: var(--rose-radius);
+  box-shadow: var(--rose-shadow);
+}
 
+.md-typeset code {
+  border-radius: 0.3rem;
+}
+
+.md-typeset table:not([class]) {
+  border-radius: var(--rose-radius);
+  overflow: hidden;
+  box-shadow: var(--rose-shadow);
+  border-collapse: separate;
+  border-spacing: 0;
+}
+
+.md-typeset table:not([class]) th {
+  background-color: var(--md-accent-fg-color--transparent);
+}
+
+.md-typeset table:not([class]) tr {
+  transition: background-color var(--rose-transition);
+}
+
+.md-typeset table:not([class]) tr:hover {
+  background-color: var(--md-accent-fg-color--transparent);
+}
+
+.md-typeset img,
+.md-typeset figure {
+  border-radius: var(--rose-radius-lg);
+}
+
+/* ---- 6. Search box: rounded, smooth focus ---------------------- */
+.md-search__form {
+  border-radius: 2rem;
+  transition: background-color var(--rose-transition), box-shadow var(--rose-transition);
+}
+
+.md-search__input:focus ~ .md-search__form,
+.md-search__form:hover {
+  box-shadow: 0 0 0 3px var(--md-accent-fg-color--transparent);
+}
+
+/* ---- 7. Buttons / copy button ----------------------------------- */
+.md-typeset .md-button,
+.md-clipboard {
+  border-radius: var(--rose-radius);
+  transition: transform var(--rose-transition), box-shadow var(--rose-transition);
+}
+
+.md-typeset .md-button:hover {
+  transform: translateY(-1px);
+  box-shadow: var(--rose-shadow);
+}
+
+/* ---- 8. Scroll-reveal (paired with scripts/custom.js) ----------- */
+.rose-reveal {
+  opacity: 0;
+  transform: translateY(8px);
+  transition: opacity 420ms ease, transform 420ms ease;
+}
+
+.rose-reveal.rose-revealed {
+  opacity: 1;
+  transform: translateY(0);
+}
+
+/* ---- 9. Config-reference table (existing component, restyled) --- */
 table#config {
   font-family: monospace;
   font-size: 13px;
@@ -22,20 +193,26 @@ table#config span.value {
   font-size: 0.9em;
   filter: opacity(70%);
   display: inline-block;
-  padding: 0px 4px;
-  border-radius: 5px;
+  padding: 1px 6px;
+  border-radius: 999px;
 }
 table#config span.example {
-  background-color: lightBlue;
+  background-color: var(--rose-100);
+  color: var(--rose-700);
 }
 table#config span.value {
-  background-color: lightGray;
+  background-color: rgba(0, 0, 0, 0.06);
 }
 table#config td.comment:nth-child(3) {
-  border-left: 2px solid whiteSmoke;
+  border-left: 2px solid rgba(0, 0, 0, 0.08);
 }
 table#config td.type {
   font-size: 0.8em;
+  filter: opacity(70%);
+  color: #999999;
+}
+table#config tr {
+  transition: background-color var(--rose-transition);
 }
 table#config tr:hover code {
   background-color: hsla(0, 0%, 100%, 1);
@@ -53,10 +230,21 @@ table#config td .anchor:target::before {
   content: "";
   display: block;
 }
-table#config td.type {
-  filter: opacity(70%);
-  color: #999999;
-}
 .md-typeset__scrollwrap {
   overflow-x: inherit;
 }
+
+/* ---- 10. Respect reduced-motion preference ----------------------- */
+@media (prefers-reduced-motion: reduce) {
+  html {
+    scroll-behavior: auto;
+  }
+  * {
+    transition-duration: 0.01ms !important;
+    animation-duration: 0.01ms !important;
+  }
+  .rose-reveal {
+    opacity: 1;
+    transform: none;
+  }
+}

docs/user-guide/acl-metrics.md

@@ -4,7 +4,7 @@ ROSE supports different Machine Learning (ML) Metrics such as `RMSE`, `MAE`, and
 
 
 ## Standard Metrics
-For a full list of the supported metrics please refer to the following link [ROSE Standard Metrics](https://github.com/radical-cybertools/ROSE/blob/feature/al_algo_selector/rose/metrics.py)
+For a full list of the supported metrics please refer to the following link [ROSE Standard Metrics](https://github.com/radical-cybertools/ROSE/blob/main/rose/metrics.py)
 
 
 ## Custom Metrics
@@ -26,3 +26,8 @@ async def check_metric(*args):
 ```
 
 In this way, ROSE will understand the relation between the custom metric and the target threshold value.
+
+!!! note
+    `metric_name` is just a label used for logging and tracking — ROSE does not validate it
+    against a fixed list. Any string is accepted as long as the decorated function returns a
+    numerical value to compare against `threshold`.