Improve the online code editor

torla-dnv · torla-dnv · commit 50eb02cfa7a8 · 2025-07-22T10:07:08.000+02:00
diff --git a/README.rst b/README.rst
@@ -60,6 +60,9 @@ Example:
 
     pip install raschii
 
+You can also run Raschii in your web browser using PyScript/Pyodide, see the 
+`online demo <https://raschii.readthedocs.io/en/latest/raschii_pyscript.html>`_!
+
 
 Using Raschii from Python
 .........................
diff --git a/documentation/_static/mini-coi.js b/documentation/_static/mini-coi.js
@@ -0,0 +1,29 @@
+/* See https://docs.pyscript.net/2025.7.3/user-guide/workers/ */
+/*! coi-serviceworker v0.1.7 - Guido Zuidhof and contributors, licensed under MIT */
+/*! mini-coi - Andrea Giammarchi and contributors, licensed under MIT */
+(({ document: d, navigator: { serviceWorker: s } }) => {
+  if (d) {
+    const { currentScript: c } = d;
+    s.register(c.src, { scope: c.getAttribute('scope') || '.' }).then(r => {
+      r.addEventListener('updatefound', () => location.reload());
+      if (r.active && !s.controller) location.reload();
+    });
+  }
+  else {
+    addEventListener('install', () => skipWaiting());
+    addEventListener('activate', e => e.waitUntil(clients.claim()));
+    addEventListener('fetch', e => {
+      const { request: r } = e;
+      if (r.cache === 'only-if-cached' && r.mode !== 'same-origin') return;
+      e.respondWith(fetch(r).then(r => {
+        const { body, status, statusText } = r;
+        if (!status || status > 399) return r;
+        const h = new Headers(r.headers);
+        h.set('Cross-Origin-Opener-Policy', 'same-origin');
+        h.set('Cross-Origin-Embedder-Policy', 'require-corp');
+        h.set('Cross-Origin-Resource-Policy', 'cross-origin');
+        return new Response(body, { status, statusText, headers: h });
+      }));
+    });
+  }
+})(self);
diff --git a/documentation/_static/raschii_pyscript.py b/documentation/_static/raschii_pyscript.py
@@ -12,20 +12,23 @@ def plot_wave():
 
     - Read the user input
     - Check the breaking criteria
-    - Generate the wave,  
-    - Plots the wave using SVG
+    - Generate the wave
+    - Show the wave profile using SVG
     - Show the wave properties in output text area
     - Show warnings and errors in the info area
 
     """
+    global current_raschii_wave
+    current_raschii_wave = None
+
     page.find("#raschii p.info").textContent = "Generating wave..."
     page.find("#raschii p.warning").textContent = ""
     page.find("#raschii p.error").textContent = ""
     page.find("#raschii_out").textContent = ""
-    SvgWavePlot.current_wave = None
 
     # Read the user input
     wave_input = WaveInput()
+    wave_input.load_from_page()
     if not wave_input.is_ok:
         page.find("#raschii p.error").textContent = wave_input.error_message
         return
@@ -71,20 +74,25 @@ def plot_wave():
         f"  Wave period    = {wave.T:.2f}",
         f"  Phase speed    = {wave.c:.3f}",
         "",
-        "Details:",
+        "Numerical details:",
         *[f"  {key}: {value}" for key, value in wave.data.items()],
     ]
     page.find("#raschii_out").textContent = "\n".join(outputs)
-    SvgWavePlot(wave=wave, x=x, eta=eta)
+    current_raschii_wave = wave
+    page.find("#raschii_plot").innerHTML = wave_profile_to_svg(x, eta)
 
 
 @pyscript.when("click", "#raschii_plot")
 def show_info_when_clicking_plot(mouse_event):
     """
-    This is called when the user clicks on the SVG plot.
+    This is called when the user clicks on the SVG wave profile.
+
+    - Get the coordinates of the clicked point in the wave coordinate system
+    - Show information about the clicked point, including particle velocities
+
     """
-    wave = SvgWavePlot.current_wave
-    if wave is None:
+    global current_raschii_wave
+    if current_raschii_wave is None:
         page.find("#raschii p.info").textContent = "No wave data available."
         return
 
@@ -93,12 +101,12 @@ def show_info_when_clicking_plot(mouse_event):
 
     # Show the information about the clicked point
     info = f"You clicked on x = {x:.3f} m, z = {z:.3f} m (from the bottom)"
-    eta = wave.surface_elevation(x=[x], t=0.0)[0]
+    eta = current_raschii_wave.surface_elevation(x=[x], t=0.0)[0]
     if z > eta:
         info += "<br>(Air)"
     else:
         info += "<br>(Water)"
-        vel = wave.velocity(x, z, all_points_wet=True)
+        vel = current_raschii_wave.velocity(x, z, all_points_wet=True)
         info += f"<br>Horizontal particle velocity: {vel[0, 0]:.3f}"
         info += f"<br>Vertical particle velocity:   {vel[0, 1]:.3f}"
 
@@ -107,37 +115,25 @@ def show_info_when_clicking_plot(mouse_event):
 
 class WaveInput:
     def __init__(self):
+        self.wave_model_name: str
+        self.height: float
+        self.depth: float
+        self.length: float
+        self.order: float
+
         self.is_ok: bool = True
         self.warning_message: str = ""
         self.error_message: str = ""
 
-        def get_input_value(name: str, converter):
-            try:
-                element = page.find(f"#raschii_{name}")
-            except Exception:
-                self.is_ok = False
-                self.error_message += f"Input element '{name}' not found.\n"
-                return None
-
-            try:
-                value = element[0].value
-            except IndexError:
-                self.is_ok = False
-                self.error_message += f"Input element '{name}' is empty!\n"
-                return None
-
-            try:
-                return converter(value)
-            except ValueError:
-                self.is_ok = False
-                self.error_message += f"Invalid value for '{name}': {value!r} is not a number!\n"
-                return None
-
-        self.wave_model_name: str = get_input_value("wave_model", str)
-        self.height: float = get_input_value("height", float)
-        self.depth: float = get_input_value("depth", float)
-        self.length: float = get_input_value("length", float)
-        self.order: float = get_input_value("order", int)
+    def load_from_page(self):
+        """
+        Load the wave input parameters from the user input on the web page
+        """
+        self.wave_model_name = self._get_page_input_value("wave_model", str)
+        self.height = self._get_page_input_value("height", float)
+        self.depth = self._get_page_input_value("depth", float)
+        self.length = self._get_page_input_value("length", float)
+        self.order = self._get_page_input_value("order", int)
 
         if self.height < 0:
             self.is_ok = False
@@ -149,50 +145,64 @@ def get_input_value(name: str, converter):
             self.is_ok = False
             self.error_message += "Wave length must be positive!\n"
 
+    def _get_page_input_value(self, name: str, converter):
+        try:
+            element = page.find(f"#raschii_{name}")
+        except Exception:
+            self.is_ok = False
+            self.error_message += f"Input element '{name}' not found.\n"
+            return None
 
-class SvgWavePlot:
-    current_wave = None
+        try:
+            value = element[0].value
+        except IndexError:
+            self.is_ok = False
+            self.error_message += f"Input element '{name}' is empty!\n"
+            return None
 
-    def __init__(self, wave, x: list[float], eta: list[float]):
-        SvgWavePlot.current_wave = wave
+        try:
+            return converter(value)
+        except ValueError:
+            self.is_ok = False
+            self.error_message += f"Invalid value for '{name}': {value!r} is not a number!\n"
+            return None
 
-        # Plot extents
-        self.xmin = min(x)
-        self.xmax = max(x)
-        eta_min = min(eta)
-        eta_max = max(eta)
-        self.ymin = max(eta_min - (eta_max - eta_min) * 0.4, 0.0)
-        self.ymax = eta_max + (eta_max - eta_min) * 0.4
 
-        self.x = [0.0, *x, x[-1]]
-        self.y = [0.0, *eta, 0.0]
-        self.eta = eta
-        self.create_svg()
+def wave_profile_to_svg(x: list[float], eta: list[float]) -> str:
+    """
+    Convert the wave profile to SVG format and returns it as string
 
-    def create_svg(self):
-        """
-        Create the SVG tags to plot the wave.
+    We need to handle the fact that SVG y-coordinates are inverted compared to
+    the wave coordinate system. The SVG origin is at the top-left corner and is
+    positive downwards, while the wave coordinate system has the origin at the
+    still water surface and is positive upwards.
+    """
+    # Plot extents
+    xmin = min(x)
+    xmax = max(x)
+    eta_min = min(eta)
+    eta_max = max(eta)
+    ymin = max(eta_min - (eta_max - eta_min) * 0.4, 0.0)
+    ymax = eta_max + (eta_max - eta_min) * 0.4
+
+    x_plot = [0.0, *x, x[-1]]
+    y_plot = [0.0, *eta, 0.0]
+    coords = " ".join(f"{x},{y}" for x, y in zip(x_plot, y_plot))
+
+    dx = xmax - xmin
+    dy = ymax - ymin
+    svg_contents = [
+        '<svg version="1.1" preserveAspectRatio="none"',
+        f'viewBox="{xmin} {-ymax} {dx} {dy}">',
+        '<g transform="scale(1,-1)">',
+        f'<path d="M{coords} z" fill="#687dc1"></path>',
+        "</g>",
+        "</svg>",
+    ]
+    return "\n".join(svg_contents)
 
-        We need to handle the fact that SVG y-coordinates are inverted compared to
-        the wave coordinate system. The SVG origin is at the top-left corner and is
-        positive downwards, while the wave coordinate system has the origin at the
-        still water surface and is positive upwards.
-        """
-        dx = self.xmax - self.xmin
-        dy = self.ymax - self.ymin
-        coords = " ".join(f"{x},{y}" for x, y in zip(self.x, self.y))
-        svg_contents = [
-            '<svg version="1.1" preserveAspectRatio="none"',
-            f'viewBox="{self.xmin} {-self.ymax} {dx} {dy}">',
-            '<g transform="scale(1,-1)">',
-            f'<path d="M{coords} z" fill="#687dc1"></path>',
-            "</g>",
-            "</svg>",
-        ]
-        page.find("#raschii_plot").innerHTML = "\n".join(svg_contents)
-
-
-def get_physical_coordinates(mouse_event):
+
+def get_physical_coordinates(mouse_event) -> tuple[float, float]:
     """
     Convert the mouse click coordinates from the SVG element to the physical
     coordinates used when creating the SVG.
diff --git a/documentation/_static/raschii_pyscript_editor.html b/documentation/_static/raschii_pyscript_editor.html
@@ -10,20 +10,35 @@
     <link rel="stylesheet" href="https://pyscript.net/releases/2025.7.3/core.css">
 
     <!-- This script tag bootstraps PyScript -->
+    <script src="./mini-coi.js"></script>
     <script type="module" src="https://pyscript.net/releases/2025.7.3/core.js"></script>
 
     <title>Raschii Web editor using PyScript</title>
 </head>
 
 <body>
-    <script type="py-editor" config='{"packages":["raschii"]}'>
+    <script type="py-editor" config='{"packages":["raschii", "matplotlib"]}'>
+        from pyscript import display, web
+        import numpy as np
+        import matplotlib.pyplot as plt
         import raschii
 
-        fwave = raschii.FentonWave(height=0.25, depth=0.5, length=2.0, N=20)
-        print(fwave.surface_elevation(x=0))
-        print(fwave.surface_elevation(x=[0, 0.1, 0.2, 0.3]))
-        print(fwave.velocity(x=0, z=0.2))
+        wave = raschii.FentonWave(height=0.20, depth=0.5, length=2.0, N=10)
+
+        x = np.linspace(-wave.length, wave.length, 101)
+        eta = wave.surface_elevation(x, t=0.0)
+
+        fig, ax = plt.subplots(figsize=(8, 4))
+        ax.axhline(wave.depth, c='k', lw=1, ls=':')
+        ax.fill_between(x, eta, eta*0, color='blue', alpha=0.5)
+
+        # Clear any prior output from the web page
+        web.page["#raschii_editor_output"].innerHTML = ""
+
+        # Display the matplotlib figure
+        display(fig, target="#raschii_editor_output")
     </script>
+    <div id="raschii_editor_output"></div>
 </body>
 
 </html>
diff --git a/documentation/raschii_pyscript.rst b/documentation/raschii_pyscript.rst
@@ -5,16 +5,21 @@ Online demo
 ===========================
 
 If you are reading this in a web browser then a demo should be shown below.
-What you are then seeing is a Raschii running in the browser using
-`PyScript <https://pyscript.net/>`_ and `Pyodide <https://pyodide.org/>`_.
+This is Raschii running in your browser using `PyScript <https://pyscript.net/>`_
+and `Pyodide <https://pyodide.org/>`_.
+Note that some numerical calculations may give slightly different results than in
+"normal" Python running on your computer.
 
+.. contents::
+   :local:
 
-Visualization
-=============
 
-You can click the figure with the wave profile to see the particle velocities.
-It takes some time to download Python, numpy, and Raschii the first time you
-run this demo, so please be patient.
+Wave visualization
+==================
+
+You can click the figure with the wave profile to see the particle velocities
+after the wave profile has been calculated.
+You can also `open in a full window <./_static/raschii_pyscript.html>`_.
 
 .. raw:: html
     
@@ -24,8 +29,8 @@ This web visualization was made after being inspired by the `original online
 wave calculators <http://www.coastal.udel.edu/faculty/rad/>`_ from the 1990s by 
 Robert A. Dalrymple, specifically the `Dean stream function wave theory 
 calculator <http://www.coastal.udel.edu/faculty/rad/streamless.html>`_.
-Unfortunately Dalrymple's calculators are based on Java applet technology which
-does not work well in modern web browsers (though, the JAR files can be 
+Unfortunately, Dalrymple's calculators are based on Java applet technology which
+does not work well in modern web browsers (though the JAR files can be 
 downloaded and run locally by a sufficiently technologically proficient user).
 
 There was once a `port of Raschii to Dart <https://bitbucket.org/trlandet/raschiidart/>`_
@@ -36,9 +41,8 @@ longer maintained.
 Online code editor
 ==================
 
-You can also write your own code using Raschii (and numpy) in the below editor.
-Press the run (play) button to run the code.
+You can write and run your own code using Raschii, numpy, and matplotlib in the online code editor.
+Press the run (play) button to run the code; this button may not appear until you start editing.
+It will take a while to run the code for the first time, but after that it is relatively fast.
 
-.. raw:: html
-    
-    <iframe src="./_static/raschii_pyscript_editor.html" height="400px" width="100%"></iframe>
+`Open the online code editor <./_static/raschii_pyscript_editor.html>`_!
