feature(first version): First version to run the simulator with parametes.

app.py

@@ -5,6 +5,7 @@ from typing import Sequence
 import matplotlib.pyplot as plt
 import numpy as np
 import torch
+import math
 
 try:
     import gradio as gr
@@ -13,41 +14,19 @@ except ModuleNotFoundError:  # pragma: no cover - optional dependency for tests
 
 from surfdisp2k25 import dispsurf2k25_simulator
 
-MODEL_SIZE = 60
-CUSTOM_MODEL_LABEL = "Custom (enter values below)"
+DISPERSION_SAMPLES = 60
+MAX_LAYERS = 100
 
-# Preset shear-wave velocity profiles (km/s) sampled over 60 layers.
-PRESET_MODELS: dict[str, np.ndarray] = {
-    "Soft Sedimentary Basin": np.concatenate(
-        [
-            np.linspace(0.8, 1.6, 20, dtype=np.float32),
-            np.linspace(1.6, 2.4, 20, dtype=np.float32),
-            np.linspace(2.4, 3.2, 20, dtype=np.float32),
-        ]
-    ),
-    "Continental Crust": np.concatenate(
-        [
-            np.linspace(2.6, 3.2, 15, dtype=np.float32),
-            np.linspace(3.2, 3.8, 25, dtype=np.float32),
-            np.linspace(3.8, 4.5, 20, dtype=np.float32),
-        ]
-    ),
-    "Oceanic Lithosphere": np.concatenate(
-        [
-            np.linspace(1.8, 2.4, 15, dtype=np.float32),
-            np.linspace(2.4, 3.4, 25, dtype=np.float32),
-            np.linspace(3.4, 4.2, 20, dtype=np.float32),
-        ]
-    ),
-}
-
-DEFAULT_CUSTOM_PROFILE = PRESET_MODELS["Continental Crust"]
-DEFAULT_TABLE = [[float(v)] for v in DEFAULT_CUSTOM_PROFILE]
-
-EARTH_MODEL_OPTIONS = {
-    "Flat Earth (iflsph=0)": 0,
-    "Spherical Earth (iflsph=1)": 1,
-}
+# Default layered model with a half-space.
+DEFAULT_CUSTOM_PROFILE: list[tuple[float, float]] = [
+    (1.0, 2.0),
+    (1.0, 2.5),
+    (1.0, 3.0),
+    (0.0, 3.5),
+]
+DEFAULT_THICKNESS = np.asarray([layer[0] for layer in DEFAULT_CUSTOM_PROFILE], dtype=np.float32)
+DEFAULT_VS = np.asarray([layer[1] for layer in DEFAULT_CUSTOM_PROFILE], dtype=np.float32)
+DEFAULT_TABLE = [[float(h), float(vs)] for h, vs in DEFAULT_CUSTOM_PROFILE]
 
 WAVE_TYPE_OPTIONS = {
     "Rayleigh waves (iwave=2)": 2,
@@ -70,69 +49,151 @@ def _fail(message: str) -> None:
     raise ValidationError(message)
 
 
-def _extract_model_values(
-    model_label: str, table_values: Sequence[Sequence[float]]
-) -> np.ndarray:
-    if model_label != CUSTOM_MODEL_LABEL:
-        return PRESET_MODELS[model_label]
+def _normalize_table(table_values: Sequence[Sequence[float]]) -> list[list[float]]:
+    if table_values is None:  # type: ignore[comparison-overlap]
+        return []
+    if hasattr(table_values, "to_numpy"):
+        return table_values.to_numpy().tolist()  # type: ignore[no-any-return]
+    if isinstance(table_values, np.ndarray):
+        return table_values.tolist()
+    return [list(row) if isinstance(row, (list, tuple, np.ndarray)) else [row] for row in table_values]  # type: ignore[misc]
+
+
+def _is_blank(value: object) -> bool:
+    if value in (None, ""):
+        return True
+    if isinstance(value, (float, np.floating)):
+        return math.isnan(value)
+    return False
+
+
+def _table_is_empty(table_values: Sequence[Sequence[float]]) -> bool:
+    rows = _normalize_table(table_values)
+    for row in rows:
+        if not isinstance(row, (list, tuple)):
+            continue
+        if len(row) < 2:
+            continue
+        if not (_is_blank(row[0]) and _is_blank(row[1])):
+            return False
+    return True
+
+
+def _extract_layer_values(
+    table_values: Sequence[Sequence[float]] | None,
+) -> tuple[np.ndarray, np.ndarray]:
+    normalized = _normalize_table(table_values)
+
+    if _table_is_empty(normalized):
+        return DEFAULT_THICKNESS.copy(), DEFAULT_VS.copy()
+
+    thickness_values: list[float] = []
+    vs_values: list[float] = []
+    for idx, row in enumerate(normalized, start=1):
+        if not isinstance(row, (list, tuple)):
+            _fail("Each layer must provide thickness and Vs.")
 
-    flattened: list[float] = []
-    for row in table_values:
-        if isinstance(row, (list, tuple)):
-            value = row[0] if row else None
-        else:
-            value = row
+        if len(row) < 2:
+            _fail(f"Layer {idx} must include both thickness and Vs.")
+
+        raw_thickness, raw_vs = row[0], row[1]
+        if _is_blank(raw_thickness) and _is_blank(raw_vs):
+            continue  # Ignore empty rows for dynamic tables
+        if _is_blank(raw_thickness) or _is_blank(raw_vs):
+            _fail(f"Layer {idx} must include both thickness and Vs.")
 
-        if value in (None, ""):
-            _fail("All 60 custom model rows must contain a value.")
         try:
-            flattened.append(float(value))
-        except (TypeError, ValueError) as exc:
-            _fail("Custom model values must be numeric.")
-
-    values = np.asarray(flattened, dtype=np.float32)
-    if values.size != MODEL_SIZE:
-        _fail(
-            f"Custom model must contain exactly {MODEL_SIZE} values "
-            f"(received {values.size})."
-        )
-    if np.any((values < 0.0) | (values > 8.0)):
-        _fail("Custom model values must stay between 0 and 8 km/s.")
-    return values
+            thickness = float(raw_thickness)
+            vs = float(raw_vs)
+        except (TypeError, ValueError):
+            _fail("Layer thickness and Vs must be numeric values.")
+
+        if thickness < 0.0:
+            _fail(f"Layer {idx} thickness must be non-negative.")
+        if vs <= 0.0:
+            _fail(f"Layer {idx} shear-wave velocity must be greater than 0.")
+
+        thickness_values.append(thickness)
+        vs_values.append(vs)
+
+    if not thickness_values:
+        _fail("Custom model must contain at least one layer.")
+
+    if len(thickness_values) > MAX_LAYERS:
+        _fail(f"Models cannot exceed {MAX_LAYERS} layers.")
+
+    thickness_array = np.asarray(thickness_values, dtype=np.float32)
+    vs_array = np.asarray(vs_values, dtype=np.float32)
+
+    if thickness_array.size == 0:
+        _fail("Custom model must contain at least one layer.")
+
+    if thickness_array[-1] != 0.0:
+        thickness_array[-1] = 0.0
+
+    if np.any(thickness_array[:-1] <= 0.0):
+        _fail("Only the final layer may have zero thickness.")
+
+    return thickness_array, vs_array
 
 
 def _build_theta(
-    vs_values: np.ndarray, vp_vs_ratio: float, min_depth: float, max_depth: float
+    thickness_values: np.ndarray, vs_values: np.ndarray, vp_vs_ratio: float
 ) -> torch.Tensor:
     if vp_vs_ratio <= 1.0:
         _fail("Vp/Vs ratio must be greater than 1.0.")
-    if max_depth <= min_depth:
-        _fail("Max depth must be greater than min depth.")
+    if thickness_values.size != vs_values.size:
+        _fail("Each layer must have a corresponding Vs value.")
 
     n_layers = vs_values.size
     if n_layers == 0:
         _fail("Model must contain at least one layer.")
-    if n_layers > 100:
-        _fail("Models cannot exceed 100 layers.")
-
-    if n_layers == 1:
-        layer_thickness = 0.0
-    else:
-        layer_thickness = (max_depth - min_depth) / (n_layers - 1)
+    if n_layers > MAX_LAYERS:
+        _fail(f"Models cannot exceed {MAX_LAYERS} layers.")
 
-    thickness = np.full(n_layers, layer_thickness, dtype=np.float32)
-    thickness[-1] = 0.0  # Half-space
+    if np.any(thickness_values < 0.0):
+        _fail("Layer thickness values must be non-negative.")
+    if thickness_values[-1] != 0.0:
+        _fail("The final layer must have zero thickness (half-space).")
+    if np.any(vs_values <= 0.0):
+        _fail("Shear-wave velocity must be positive.")
 
     theta = np.concatenate(
         [
             np.array([float(n_layers), float(vp_vs_ratio)], dtype=np.float32),
-            thickness,
+            thickness_values.astype(np.float32),
             vs_values.astype(np.float32),
         ]
     )
     return torch.from_numpy(theta).unsqueeze(0)
 
 
+def _make_model_plot(
+    thickness_values: np.ndarray, vs_values: np.ndarray
+):
+    min_depth = 0.0
+    cumulative_depth = np.cumsum(thickness_values)
+    depth_edges = min_depth + np.concatenate(([0.0], cumulative_depth))
+    velocity_steps = np.concatenate((vs_values, [vs_values[-1]]))
+
+    plot_depth = np.concatenate((depth_edges, [depth_edges[-1] + 1.0]))
+    plot_velocity = np.concatenate((velocity_steps, [velocity_steps[-1]]))
+
+    max_depth = depth_edges[-1] + 1.0
+    if max_depth <= min_depth:
+        max_depth = min_depth + 1.0
+
+    fig, ax = plt.subplots(figsize=(7, 4))
+    ax.step(plot_depth, plot_velocity, where="post", linewidth=1.5)
+    ax.set_xlabel("Depth (km)")
+    ax.set_ylabel("Shear velocity (km/s)")
+    ax.set_title("Layered Vs model")
+    ax.set_xlim(min_depth, max_depth)
+    ax.grid(True, linestyle="--", linewidth=0.6, alpha=0.5)
+    fig.tight_layout()
+    return fig
+
+
 def _make_plot(periods: np.ndarray, velocities: np.ndarray):
     fig, ax = plt.subplots(figsize=(7, 4))
     ax.plot(periods, velocities, marker="o", markersize=3, linewidth=1.5)
@@ -144,20 +205,56 @@ def _make_plot(periods: np.ndarray, velocities: np.ndarray):
     return fig
 
 
+def _layers_to_table(thickness: np.ndarray, vs: np.ndarray) -> list[list[float]]:
+    return [[float(h), float(v)] for h, v in zip(thickness, vs)]
+
+
+def _generate_random_model() -> tuple[np.ndarray, np.ndarray]:
+    rng = np.random.default_rng()
+    n_layers = int(rng.integers(2, 21))
+    finite_thickness = rng.uniform(0.1, 3.0, size=n_layers - 1).astype(np.float32)
+    vs_values = rng.uniform(2.0, 8.0, size=n_layers - 1).astype(np.float32)
+    thickness = np.concatenate([finite_thickness, np.array([0.0], dtype=np.float32)])
+    last_vs = float(rng.uniform(2.0, 8.0))
+    while abs(last_vs - float(vs_values[-1])) < 1e-3:
+        last_vs = float(rng.uniform(2.0, 8.0))
+    vs = np.concatenate([vs_values, np.array([last_vs], dtype=np.float32)])
+    return thickness, vs
+
+
+def on_layer_table_change(
+    table_values: Sequence[Sequence[float]] | None,
+):
+    if gr is None:
+        raise RuntimeError("Gradio is required for interactive updates.")
+
+    thickness, vs = _extract_layer_values(table_values)
+    sanitized_table = _layers_to_table(thickness, vs)
+    plot = _make_model_plot(thickness, vs)
+
+    return sanitized_table, plot
+
+
+def on_random_model_click():
+    if gr is None:
+        raise RuntimeError("Gradio is required for interactive updates.")
+
+    thickness, vs = _generate_random_model()
+    table = _layers_to_table(thickness, vs)
+    plot = _make_model_plot(thickness, vs)
+    return table, plot
+
+
 def run_simulation(
-    model_label: str,
-    custom_values: Sequence[Sequence[float]],
-    min_depth: float,
-    max_depth: float,
+    custom_values: Sequence[Sequence[float]] | None,
     vp_vs_ratio: float,
     p_min: float,
     p_max: float,
-    earth_model_label: str,
     wave_type_label: str,
     mode: int,
     group_label: str,
 ):
-    vs_values = _extract_model_values(model_label, custom_values)
+    thickness_values, vs_values = _extract_layer_values(custom_values)
 
     if p_min <= 0.0 or p_max <= 0.0:
         _fail("Periods must be positive numbers.")
@@ -165,9 +262,11 @@ def run_simulation(
         _fail("Maximum period must be greater than minimum period.")
     if mode < 1:
         _fail("Mode number must be at least 1.")
+    if mode > 3:
+        _fail("Mode number cannot exceed 3 in this simulator.")
 
-    theta = _build_theta(vs_values, vp_vs_ratio, min_depth, max_depth)
-    iflsph = EARTH_MODEL_OPTIONS[earth_model_label]
+    theta = _build_theta(thickness_values, vs_values, vp_vs_ratio)
+    iflsph = 0  # Always use flat Earth
     iwave = WAVE_TYPE_OPTIONS[wave_type_label]
     igr = GROUP_VELOCITY_OPTIONS[group_label]
 
@@ -176,7 +275,7 @@ def run_simulation(
             theta=theta,
             p_min=float(p_min),
             p_max=float(p_max),
-            kmax=MODEL_SIZE,
+            kmax=DISPERSION_SAMPLES,
             iflsph=iflsph,
             iwave=iwave,
             mode=int(mode),
@@ -188,52 +287,64 @@ def run_simulation(
 
     velocities = disp.squeeze(0).detach().cpu().numpy()
     periods = np.linspace(p_min, p_max, velocities.size)
-    plot = _make_plot(periods, velocities)
+    dispersion_plot = _make_plot(periods, velocities)
+    model_plot = _make_model_plot(thickness_values, vs_values)
 
     table = [[float(p), float(v)] for p, v in zip(periods, velocities)]
 
-    layer_thickness = 0.0 if vs_values.size <= 1 else (max_depth - min_depth) / (
-        vs_values.size - 1
-    )
+    finite_thickness = thickness_values[:-1] if thickness_values.size > 1 else thickness_values
+    total_depth = float(np.sum(finite_thickness))
+    max_depth = total_depth
+    n_finite_layers = finite_thickness.size
     summary = "\n".join(
         [
-            f"**Model**: {model_label}",
-            f"**Layers**: {vs_values.size} (Δz ≈ {layer_thickness:.2f} km)",
+            "**Model**: Custom layered model",
+            f"**Layers**: {vs_values.size} (including half-space)",
+            f"**Finite thickness layers**: {n_finite_layers}",
+            f"**Depth window**: 0.00 – {max_depth:.2f} km",
+            f"**Vp/Vs ratio**: {vp_vs_ratio:.2f}",
             f"**Vs range**: {vs_values.min():.2f} – {vs_values.max():.2f} km/s",
+            f"**Total thickness**: {total_depth:.2f} km",
             f"**Periods**: {p_min:.2f} – {p_max:.2f} s ({velocities.size} samples)",
             f"**Wave type**: {wave_type_label}; mode = {int(mode)}",
             f"**Phase velocity range**: {velocities.min():.2f} – {velocities.max():.2f} km/s",
         ]
     )
 
-    return plot, table, summary
+    return model_plot, dispersion_plot, table, summary
 
 
 if gr is not None:
     with gr.Blocks(title="SurfDisp2k25 Simulator") as demo:
         gr.Markdown(
-            "### SurfDisp2k25 dispersion simulator\n"
-            "Select a preset velocity profile or switch to custom mode to edit the "
-            "60 Vs values (km/s) sampled between the minimum and maximum depth."
+            """## SurfDisp2k25 - Interactive Surface Wave Dispersion Simulator (Alpha)
+
+This simulator computes surface wave dispersion curves (Love and Rayleigh waves) for layered Earth models.
+You can define layer thicknesses and shear-wave velocities manually or generate a random model.
+
+**Parameters**
+
+- Minimum/Maximum period (s) - Range of periods used to compute the dispersion curve.
+- Wave type - Choose between Rayleigh (vertical-radial motion) and Love (horizontal shear) waves.
+- Mode number - Number of modes (fundamental plus higher harmonics) to compute.
+- Velocity output - Select whether to compute only phase velocity or both phase and group velocity.
+- Vp/Vs ratio - Defines the P-wave velocity from the S-wave velocity.
+
+The simulator displays both the layered Vs model and the resulting dispersion curve.
+This is an alpha version; results may contain numerical artefacts, so use with caution for testing and visualization."""
         )
 
         with gr.Row():
             with gr.Column():
-                model_selector = gr.Dropdown(
-                    choices=[*PRESET_MODELS.keys(), CUSTOM_MODEL_LABEL],
-                    value="Continental Crust",
-                    label="Shear-wave velocity model",
-                )
+                random_button = gr.Button("Generate random model")
                 custom_model = gr.Dataframe(
-                    headers=["Vs (km/s)"],
+                    headers=["Thickness (km)", "Vs (km/s)"],
                     value=DEFAULT_TABLE,
-                    row_count=(MODEL_SIZE, "fixed"),
-                    col_count=(1, "fixed"),
-                    datatype="float",
-                    label="Custom Vs profile (used when Custom is selected)",
+                    row_count=(len(DEFAULT_TABLE), "dynamic"),
+                    col_count=(2, "fixed"),
+                    datatype=["float", "float"],
+                    label="Custom layered model",
                 )
-                min_depth_input = gr.Number(value=0.0, label="Minimum depth (km)")
-                max_depth_input = gr.Number(value=30.0, label="Maximum depth (km)")
                 vpvs_input = gr.Slider(
                     minimum=1.5,
                     maximum=2.2,
@@ -244,11 +355,6 @@ if gr is not None:
             with gr.Column():
                 p_min_input = gr.Number(value=1.0, label="Minimum period (s)")
                 p_max_input = gr.Number(value=30.0, label="Maximum period (s)")
-                earth_model_input = gr.Radio(
-                    choices=list(EARTH_MODEL_OPTIONS.keys()),
-                    value="Flat Earth (iflsph=0)",
-                    label="Earth model",
-                )
                 wave_type_input = gr.Radio(
                     choices=list(WAVE_TYPE_OPTIONS.keys()),
                     value="Rayleigh waves (iwave=2)",
@@ -256,7 +362,7 @@ if gr is not None:
                 )
                 mode_input = gr.Slider(
                     minimum=1,
-                    maximum=5,
+                    maximum=3,
                     value=1,
                     step=1,
                     label="Mode number",
@@ -269,33 +375,52 @@ if gr is not None:
                 run_button = gr.Button("Run simulation", variant="primary")
 
         with gr.Row():
+            model_plot_output = gr.Plot(label="Shear-wave velocity profile")
             plot_output = gr.Plot(label="Dispersion curve")
+
+        with gr.Row():
             table_output = gr.Dataframe(
                 headers=["Period (s)", "Phase velocity (km/s)"],
                 datatype="float",
                 col_count=(2, "fixed"),
-                row_count=(MODEL_SIZE, "dynamic"),
+                row_count=(DISPERSION_SAMPLES, "dynamic"),
                 label="Sampled dispersion values",
             )
 
         summary_output = gr.Markdown()
 
+        demo.load(
+            fn=lambda: _make_model_plot(DEFAULT_THICKNESS, DEFAULT_VS),
+            inputs=None,
+            outputs=model_plot_output,
+        )
+
+        custom_model.change(
+            fn=on_layer_table_change,
+            inputs=custom_model,
+            outputs=[custom_model, model_plot_output],
+            trigger_mode="always_last",
+            queue=False,
+        )
+
+        random_button.click(
+            fn=on_random_model_click,
+            inputs=None,
+            outputs=[custom_model, model_plot_output],
+        )
+
         run_button.click(
             fn=run_simulation,
             inputs=[
-                model_selector,
                 custom_model,
-                min_depth_input,
-                max_depth_input,
                 vpvs_input,
                 p_min_input,
                 p_max_input,
-                earth_model_input,
                 wave_type_input,
                 mode_input,
                 group_mode_input,
             ],
-            outputs=[plot_output, table_output, summary_output],
+            outputs=[model_plot_output, plot_output, table_output, summary_output],
         )
 else:  # pragma: no cover - allows importing without gradio installed
     demo = None