bf_fields.py

"""Data-driven parameter registry for the Brain-Folding Simulator (extended).

Everything the UI knows about a parameter lives here: its ``Parameters.prm``
key, label, section, widget kind, 2D/3D preset, validator, enable rule, and the
Parameter-Guide metadata (symbol, unit, recommended range, figure, help text).

This module imports nothing from the app — it is pure data plus validator
callables — so ``BFSimulator.py``, ``bf_widgets.py`` and ``bf_style.py`` stay
fully generic and adding a parameter needs no UI change.

Two registries:

* ``FIELDS``  — one entry per row shown on a card (34 rows).
* ``GROUPS``  — sub-parameters edited in a dialog behind a single card row: the
  9x5 cell-lineage ratio matrix, the phase timeline, the per-cell-type
  migration speeds and diffusivities (56 keys).

``PRM_FIELDS`` flattens both into the list that the .prm reader/writer walks,
so a grouped value validates and round-trips exactly like a top-level one.
"""

from __future__ import annotations

from dataclasses import dataclass
from typing import Callable, Optional

# --- section identity --------------------------------------------------------
GEOMETRY = "Geometry Parameters"
DIFFUSION = "Advection diffusion Parameters"
STIFFNESS = "Mechanical properties Parameters"
MESH = "Discretization Parameters"
SOLVER = "Numerical solver Parameters"
GROWTH = "Growth Parameters"

SECTION_ORDER = [GEOMETRY, DIFFUSION, STIFFNESS, MESH, SOLVER, GROWTH]

OSVZ_OPTIONS = ["Constant", "Linear-gradient", "Quadratic-gradient", "Random1", "Random2"]

# Cell types used by the results browser and the lineage editor.
CELL_TYPES = [("RG", "RG"), ("ORG", "ORG"), ("IP", "IP"), ("NU", "NU")]


@dataclass
class Info:
    """What the guide panel shows when a field (or a specific option) is focused."""
    text: str = ""
    img: Optional[tuple[str, str]] = None      # (light, dark) filenames in Images/
    curve: Optional[tuple[str, str]] = None    # secondary figure (OSVZ curves)
    url: Optional[str] = None
    url_text: Optional[str] = None


@dataclass
class Field:
    key: str
    label: str
    section: str
    kind: str = "entry"                        # entry | combo | radio | group
    prm: Optional[str] = None                  # key in Parameters.prm (None = not written)
    options: Optional[list[tuple[str, str]]] = None   # (display, value)
    info: object = None                        # Info, or dict[value -> Info]
    default_2d: str = ""
    default_3d: str = ""
    required: bool = True
    validate: Optional[Callable[[str, dict], bool]] = None   # True when the value is OK
    enabled_when: Optional[Callable[[dict], bool]] = None    # True when the row is editable
    group: Optional[str] = None                # for kind="group": key into GROUPS
    unit: str = "—"
    symbol: str = "—"
    hint: str = "—"
    error_msg: str = "Invalid value."


# --- validators --------------------------------------------------------------
# Contract: return True when the value is acceptable. Unparseable or empty input
# returns True — emptiness is reported separately by the required-field guard.
def _f(s: str):
    try:
        return float(s)
    except (TypeError, ValueError):
        return None


def _v_vz(v, ctx):
    x = _f(v)
    return True if x is None else 0.2 <= x <= 0.4


def _v_svz(v, ctx):
    x = _f(v)
    if x is None:
        return True
    lo = _f(ctx.get("vz_raduis", ""))
    if lo is not None and x < lo:
        return False
    return x <= 0.5


def _v_cr(v, ctx):
    x = _f(v)
    return True if x is None else 0.01 <= x <= 0.35


def _v_mst(v, ctx):
    x = _f(v)
    return True if x is None else x <= 0.1


def _v_poisson(v, ctx):
    x = _f(v)
    return True if x is None else 0.0 <= x <= 0.5


def _v_cmax(v, ctx):
    x = _f(v)
    return True if x is None else x > 200


def _v_stability(v, ctx):
    x = _f(v)
    return True if x is None else x <= 0.1


def _v_ck(v, ctx):
    x = _f(v)
    return True if x is None else x <= 1


def _v_newton(v, ctx):
    x = _f(v)
    return True if x is None else x >= 3


def _v_tol(v, ctx):
    x = _f(v)
    return True if x is None else x <= 1.0e-4


def _v_tol_update(v, ctx):
    x = _f(v)
    return True if x is None else x <= 1.0e-3


def _v_delt_t(v, ctx):
    x = _f(v)
    return True if x is None else 0.0 < x < 1.0


def _v_int(v, ctx):
    if not str(v).strip():
        return True
    try:
        int(str(v))
    except ValueError:
        return False
    return True


def _v_pos_int(v, ctx):
    if not str(v).strip():
        return True
    try:
        return int(str(v)) != 0
    except ValueError:
        return False


def _v_k_growth(v, ctx):
    x = _f(v)
    if x is None:
        return True
    return x <= 1.0e-4 if ctx.get("case") == "3" else x <= 1.0e-3


def _v_ratio_cell(v, ctx):
    """A lineage-ratio cell: an integer between 0 and 4 (Patterns::Integer(-1,4))."""
    if not str(v).strip():
        return True
    try:
        return 0 <= int(str(v)) <= 4
    except ValueError:
        return False


def _v_phase(v, ctx):
    """A phase boundary in slider units: 0..147 maps to gestational week 4..48."""
    if not str(v).strip():
        return True
    try:
        return 0 <= int(float(str(v))) <= 147
    except ValueError:
        return False


def _v_non_negative(v, ctx):
    x = _f(v)
    return True if x is None else x >= 0


# --- grouped sub-parameters --------------------------------------------------
# Nine lineage transitions x five division phases. Presented as the interactive
# lineage-tree editor; stored as 45 independent .prm keys.
LINEAGES: list[tuple[str, str, str]] = [
    ("RG_RG_n", "RG/RG_n", "RG → RG"),
    ("IP_RG_n", "IP/RG_n", "RG → IP"),
    ("OR_RG_n", "OR/RG_n", "RG → ORG"),
    ("NU_RG_n", "NU/RG_n", "RG → NU"),
    ("IP_OR_n", "IP/OR_n", "ORG → IP"),
    ("OR_OR_n", "OR/OR_n", "ORG → ORG"),
    ("NU_OR_n", "NU/OR_n", "ORG → NU"),
    ("IP_IP_n", "IP/IP_n", "IP → IP"),
    ("NU_IP_n", "NU/IP_n", "IP → NU"),
]

# Same matrix for 2D and 3D.
LINEAGE_DEFAULTS: dict[str, list[str]] = {
    "RG_RG_n": ["2", "1", "1", "1", "1"],
    "IP_RG_n": ["0", "1", "0", "0", "0"],
    "OR_RG_n": ["0", "0", "1", "0", "0"],
    "NU_RG_n": ["0", "0", "0", "0", "0"],
    "IP_OR_n": ["0", "0", "0", "1", "0"],
    "OR_OR_n": ["0", "0", "1", "1", "1"],
    "NU_OR_n": ["0", "0", "0", "0", "0"],
    "IP_IP_n": ["0", "0", "1", "1", "0"],
    "NU_IP_n": ["0", "0", "2", "2", "4"],
}

# Which source population each lineage draws from — drives the dialog layout and
# the cascading enable rule (a phase's row is live only once its parent exists).
LINEAGE_SOURCE: dict[str, str] = {
    "RG_RG_n": "RG", "IP_RG_n": "RG", "OR_RG_n": "RG", "NU_RG_n": "RG",
    "IP_OR_n": "OR", "OR_OR_n": "OR", "NU_OR_n": "OR",
    "IP_IP_n": "IP", "NU_IP_n": "IP",
}

_MATRIX_FIELDS: list[Field] = []
for _lin, _prm, _title in LINEAGES:
    for _p in range(1, 6):
        _MATRIX_FIELDS.append(Field(
            key=f"{_lin}_ph{_p}",
            label=f"{_title} · phase {_p}",
            section=DIFFUSION,
            prm=f"set {_prm} P{_p}",
            default_2d=LINEAGE_DEFAULTS[_lin][_p - 1],
            default_3d=LINEAGE_DEFAULTS[_lin][_p - 1],
            validate=_v_ratio_cell,
            unit="cells", symbol=f"n_{{{_prm}}}", hint="0 – 4",
            error_msg="Must be a whole number between 0 and 4."))

_PHASE_FIELDS: list[Field] = [
    Field("first_phase", "First phase", DIFFUSION, prm="set First phase",
          default_2d="21", default_3d="15", validate=_v_phase,
          unit="GW step", symbol="t_1", hint="0 – 147",
          error_msg="Must be a whole number between 0 and 147."),
    Field("second_phase", "Second phase", DIFFUSION, prm="set Second phase",
          default_2d="49", default_3d="22", validate=_v_phase,
          unit="GW step", symbol="t_2", hint="≥ first phase",
          error_msg="Must be a whole number between 0 and 147."),
    Field("third_phase", "Third phase", DIFFUSION, prm="set Third phase",
          default_2d="84", default_3d="45", validate=_v_phase,
          unit="GW step", symbol="t_3", hint="≥ second phase",
          error_msg="Must be a whole number between 0 and 147."),
    Field("fourth_phase", "Fourth phase", DIFFUSION, prm="set Fourth phase",
          default_2d="105", default_3d="75", validate=_v_phase,
          unit="GW step", symbol="t_4", hint="≥ third phase",
          error_msg="Must be a whole number between 0 and 147."),
]

_MIGRATION_FIELDS: list[Field] = [
    Field("IP_migration", "Intermediate progenitor cell's translocation speed:", DIFFUSION,
          prm="set IP cell migration speed", default_2d="0.25", default_3d="0.25",
          validate=_v_non_negative, unit="mm/wk", symbol="v_{IP}", hint="≥ 0",
          error_msg="Must not be negative."),
    Field("OR_migration", "Outer radial glial cell's translocation speed:", DIFFUSION,
          prm="set ORG cell migration speed", default_2d="10", default_3d="10",
          validate=_v_non_negative, unit="mm/wk", symbol="v_{ORG}", hint="≥ 0",
          error_msg="Must not be negative."),
    Field("NU_migration", "Neurons cell's migration speed:", DIFFUSION,
          prm="set NU cell migration speed", default_2d="5", default_3d="5",
          validate=_v_non_negative, unit="mm/wk", symbol="v_{NU}", hint="≥ 0",
          error_msg="Must not be negative."),
]

_DIFFUSIVITY_FIELDS: list[Field] = [
    Field("RG_diffusivity", "Radial glial cell's diffusivity value:", DIFFUSION,
          prm="set RG diffusivity", default_2d="0.1", default_3d="0.1",
          validate=_v_non_negative, unit="mm²/wk", symbol="d_{RG}", hint="≥ 0",
          error_msg="Must not be negative."),
    Field("IP_diffusivity", "Intermediate progenitor cell's diffusivity value:", DIFFUSION,
          prm="set IP diffusivity", default_2d="0.1", default_3d="0.1",
          validate=_v_non_negative, unit="mm²/wk", symbol="d_{IP}", hint="≥ 0",
          error_msg="Must not be negative."),
    Field("OR_diffusivity", "Outer radial glial cell's diffusivity value:", DIFFUSION,
          prm="set ORG diffusivity", default_2d="0.1", default_3d="0.1",
          validate=_v_non_negative, unit="mm²/wk", symbol="d_{ORG}", hint="≥ 0",
          error_msg="Must not be negative."),
    Field("NU_diffusivity", "Neurons cell's diffusivity value:", DIFFUSION,
          prm="set NU diffusivity", default_2d="0.1", default_3d="0.1",
          validate=_v_non_negative, unit="mm²/wk", symbol="d_{NU}", hint="≥ 0",
          error_msg="Must not be negative."),
]

GROUPS: dict[str, list[Field]] = {
    "division_matrix": _MATRIX_FIELDS,
    "phase_timeline": _PHASE_FIELDS,
    "migration_speed": _MIGRATION_FIELDS,
    "diffusivity": _DIFFUSIVITY_FIELDS,
}

# Title / figure for each group dialog.
GROUP_META: dict[str, dict] = {
    "division_matrix": {
        "title": "Adjust cells division rate values",
        "img": ("cell_divsion.png", "cell_divsion_dark.png"),
    },
    "phase_timeline": {
        "title": "Adjust phases timeline",
        "img": ("GW.png", "GW_dark.png"),
    },
    "migration_speed": {
        "title": "Adjust cells migration speed",
        "img": ("adv_dif_eq_v_light.png", "adv_dif_eq_v_dark.png"),
    },
    "diffusivity": {
        "title": "Adjust cells diffusivity values",
        "img": ("adv_dif_eq_d_light.png", "adv_dif_eq_d_dark.png"),
    },
}

# Per-cell-type icons used by the group dialogs.
CELL_ICON = {"RG": "RG.png", "OR": "OR.png", "IP": "IP.png", "NU": "NU.png"}
CELL_ICON_EMPTY = "nonR.png"


# --- the card rows -----------------------------------------------------------
FIELDS: list[Field] = [
    # ---------------- Geometry ----------------
    Field("vz_raduis", "Ventricular zone raduis:", GEOMETRY,
          prm="set Ventricular zone raduis", default_2d="0.25", default_3d="0.25",
          validate=_v_vz,
          info=Info("Ventricular zone raduis as a ratio to initial radius\n"
                    "should take a value between 0.2 and 0.4.",
                    img=("gemotry_vz_light.png", "gemotry_vz_dark.png")),
          unit="ratio", symbol="r_{VZ}", hint="0.2 – 0.4",
          error_msg="Must be between 0.2 and 0.4."),
    Field("svz_raduis", "Subventricular zone raduis:", GEOMETRY,
          prm="set Subventricular zone raduis", default_2d="0.4", default_3d="0.4",
          validate=_v_svz,
          info=Info("Inner subventricular zone raduis as a ratio to initial radius\n"
                    "should take a value between ventricular zone raduis and 0.5.",
                    img=("gemotry_isvz_light.png", "gemotry_isvz_dark.png")),
          unit="ratio", symbol="r_{ISVZ}", hint="≥ r_VZ, ≤ 0.5",
          error_msg="Must be ≥ the ventricular zone raduis and ≤ 0.5."),
    Field("cr_thickness", "Cortex thickness:", GEOMETRY,
          prm="set Cortex thickness", default_2d="0.1", default_3d="0.1",
          validate=_v_cr,
          info=Info("Initial cortex thickness as a ratio to initial radius\n"
                    "should take a value between 0.01 and 0.35.",
                    img=("gemotry_tc_light.png", "gemotry_tc_dark.png")),
          unit="ratio", symbol="t_C", hint="0.01 – 0.35",
          error_msg="Must be between 0.01 and 0.35."),
    Field("intial_raduis", "Initial brain radius:", GEOMETRY,
          prm="set Initial radius", default_2d="2", default_3d="2",
          info=Info("Initial fetal brain radius at gestational week 5 in [mm].",
                    img=("gemotry_R_light.png", "gemotry_R_dark.png")),
          unit="mm", symbol="R_0", hint="—"),
    Field("MST_factor", "Mitotic translocation factor:", GEOMETRY,
          prm="set Mitotic somal translocation factor", default_2d="0.02", default_3d="0.02",
          validate=_v_mst,
          info=Info("Mitotic somal translocation factor of ORGCs\n"
                    "should take a value smaller than 0.1.",
                    img=("gemotry_mst_light.png", "gemotry_mst_dark.png")),
          unit="—", symbol="k_{MST}", hint="≤ 0.1",
          error_msg="Must be smaller than or equal to 0.1."),

    # ---------------- Advection–Diffusion ----------------
    Field("division_matrix", "Cells division ratios:", DIFFUSION,
          kind="group", group="division_matrix", required=False,
          info=Info("The number of daughter cells produced by each division type, per "
                    "division phase. Open the editor to set the full lineage matrix; the "
                    "tree shows the resulting population after every phase.",
                    img=("cell_divsion_guid.png", "cell_divsion_guid.png")),
          unit="cells", symbol="n_{i/j}", hint="0 – 4 per cell"),
    Field("phase_timeline", "Phases timeline:", DIFFUSION,
          kind="group", group="phase_timeline", required=False,
          info=Info("The gestational day on which each of the four division phases ends.\n"
                    "Each phase must end after the one before it.",
                    img=("GW.png", "GW_dark.png")),
          unit="GW", symbol="t_i", hint="0 – 147 (GW 4 – 48)"),
    Field("ORG_variation_case", "Distribution of OSVZ proliferation:", DIFFUSION,
          kind="combo", prm=None,
          options=[(o, o) for o in OSVZ_OPTIONS],
          default_2d="Constant", default_3d="Constant",
          info={
              "Constant": Info(
                  "The variable controllers the regional variation of ORGCs.\n"
                  "Constant mean no regional variation.",
                  img=("OSVZ_Constant.png", "OSVZ_Constant.png")),
              "Linear-gradient": Info(
                  "The variable controllers the regional variation of ORGCs.\n"
                  "The ORGCs division rate increases linearly between\nthe angle 0 and 90.",
                  img=("OSVZ_Linear_gradient.png", "OSVZ_Linear_gradient.png"),
                  curve=("Linear_gradient_curve.png", "Linear_gradient_curve_dark.png")),
              "Quadratic-gradient": Info(
                  "The variable controllers the regional variation of ORGCs.\n"
                  "The ORGCs division rate increases quadratically\nbetween the angle 0 and 90.",
                  img=("OSVZ_Quadratic_gradient.png", "OSVZ_Quadratic_gradient.png"),
                  curve=("Quadratic_gradient_curve.png", "Quadratic_gradient_curve_dark.png")),
              "Random1": Info(
                  "The variable controllers the regional variation of ORGCs.\n"
                  "The random variation of ORGCs division rate as shown in Figure.",
                  img=("OSVZ_Random1.png", "OSVZ_Random1.png"),
                  curve=("OSVZ_Random1_curve.png", "OSVZ_Random1_curve_dark.png")),
              "Random2": Info(
                  "The variable controllers the regional variation of ORGCs.\n"
                  "The random variation of ORGCs division rate as shown in Figure.",
                  img=("OSVZ_Random2.png", "OSVZ_Random2.png"),
                  curve=("OSVZ_Random2_curve.png", "OSVZ_Random2_curve_dark.png")),
          },
          unit="—", symbol="—", hint="—",
          error_msg="Not written to Parameters.prm — this solver has no OSVZ variation term."),
    Field("intial_division", "Initial cell density value:", DIFFUSION,
          prm="set Cell dvision intial value", default_2d="1000", default_3d="10000",
          info=Info("Cell density intial value in ventricular zone in [1/(mm^2)]."),
          unit="1/mm²", symbol="c_0", hint="—"),
    Field("migration_speed", "Cell migration speed:", DIFFUSION,
          kind="group", group="migration_speed", required=False,
          info=Info("Cell migration speed in [mm/wk].\nThe cells migrate along RGC fibers\n"
                    "i.e. radial direction.",
                    img=("adv_dif_eq_v_light.png", "adv_dif_eq_v_dark.png")),
          unit="mm/wk", symbol="v", hint="per cell type"),
    Field("diffusivity", "Diffusivity:", DIFFUSION,
          kind="group", group="diffusivity", required=False,
          info=Info("Diffusivity in cortex in [mm^2/wk].\nIn this model, we consider isotropic "
                    "diffusion\nwhich means the diffusion is equal in all\ndirections.",
                    img=("adv_dif_eq_d_light.png", "adv_dif_eq_d_dark.png")),
          unit="mm²/wk", symbol="d^{cc}", hint="per cell type"),
    Field("migration_threshold", "Cell migration threshold:", DIFFUSION,
          prm="set Cell migration threshold", default_2d="500", default_3d="500",
          info=Info("Cell migration threshold in [1/mm^3].",
                    img=("adv_dif_eq_c0_light.png", "adv_dif_eq_c0_dark.png")),
          unit="1/mm³", symbol="c_0", hint="—"),
    Field("HV_exp", "Heaviside function exponent:", DIFFUSION,
          prm="set Heaviside function exponent", default_2d="0.008", default_3d="0.008",
          info=Info("Heaviside function exponent.\nFor a smooth solution, should take a value\n"
                    "smaller than 0.01.",
                    img=("adv_dif_eq_gamma_light.png", "adv_dif_eq_gamma_dark.png")),
          unit="—", symbol=r"\gamma", hint="< 0.01"),

    # ---------------- Mechanical properties ----------------
    Field("stiffness_case", "Cortical stiffness case:", STIFFNESS,
          kind="radio", prm="set The state of the stiffness",
          options=[("Varying", "Varying"), ("Constant", "Constant")],
          default_2d="Varying", default_3d="Varying",
          info={
              "Varying": Info("The state of cortical stiffness. Varying means exists a positive "
                              "relation with cell density value.",
                              img=("varying.png", "varying_dark.png")),
              "Constant": Info("The state of cortical stiffness is constant."),
          },
          unit="—", symbol="—", hint="Varying / Constant"),
    Field("shear_modulus", "Cortical shear modulus:", STIFFNESS,
          prm="set The shear modulus of conrtex", default_2d="2.07", default_3d="2.07",
          info=Info("The shear modulus of the cortical layer in [KPa]. "
                    "The recommended value according to literature is 2.07 KPa.",
                    img=("strain_Energy_mu_light.png", "strain_Energy_mu_dark.png")),
          unit="kPa", symbol=r"\mu", hint="≈ 2.07"),
    Field("stiffness_ratio", "Stiffness ratio:", STIFFNESS,
          prm="set The ratio of stiffness", default_2d="3", default_3d="3",
          info=Info("The ratio of stiffness between cortex and subcortex. "
                    "The recommended values 3 and 5.",
                    img=("strain_Energy_ratio_light.png", "strain_Energy_ratio_dark.png")),
          unit="—", symbol=r"\mu_c/\mu_s", hint="3 – 5"),
    Field("poisson_ratio", "Poisson's ratio:", STIFFNESS,
          prm="set Poisson's ratio", default_2d="0.38", default_3d="0.38",
          validate=_v_poisson,
          info=Info("The value of the Poisson's ratio, have to take a vlaue between 0.0 and 0.5.",
                    img=("strain_Energy_nu_light.png", "strain_Energy_nu_dark.png"),
                    url="https://en.wikipedia.org/wiki/Poisson%27s_ratio",
                    url_text="For more details click here"),
          unit="—", symbol=r"\nu", hint="0.0 – 0.5",
          error_msg="Must be between 0.0 and 0.5."),
    Field("max_density", "Maximum cell density:", STIFFNESS,
          prm="set The max cell density", default_2d="700", default_3d="700",
          validate=_v_cmax,
          enabled_when=lambda v: v.get("stiffness_case") != "Constant",
          info=Info("The max cell density, after this value the stiffness becomes constant and "
                    "equals to value set in (shear modulus of cortex). Here the c_min was set to "
                    "200, so the c_max have to be bigger than 200.",
                    img=("varying_cmax_light.png", "varying_cmax_dark.png")),
          unit="1/mm²", symbol="c_{max}", hint="> 200",
          error_msg="Must be greater than 200."),

    # ---------------- Discretization ----------------
    Field("case", "Geometry:", MESH,
          kind="radio", prm=None,                 # passed as argv to the solver
          options=[("2D", "2"), ("3D", "3")],
          default_2d="2", default_3d="3",
          info={
              "2": Info("Two-dimensional geometry.", img=("2D_light.png", "2D_dark.png")),
              "3": Info("Three-dimensional geometry.", img=("3D_light.png", "3D_dark.png")),
          },
          unit="—", symbol="dim", hint="2D / 3D"),
    Field("refinement", "Number global refinements:", MESH,
          prm="set Number global refinements", default_2d="3", default_3d="2",
          validate=_v_int,
          info=Info("The number of mesh global\nrefinements. With increasing this\n"
                    "value the mesh becomes finer\nand the solution smoother but\n"
                    "with a longer solving time.\nThe recommended value for the\n"
                    "2D case is 3 and for the 3D\ncase is 2.",
                    img=("ref_2d_light.png", "ref_2d_dark.png")),
          unit="—", symbol="n_{ref}", hint="2D: 3 · 3D: 2",
          error_msg="Must be a whole number."),
    Field("degree", "Polynomial degree:", MESH,
          prm="set Poly degree", default_2d="2", default_3d="2",
          validate=_v_pos_int,
          info=Info("The shape function polynomial degree of the FE. The shape function is used "
                    "to approximate the solution.\nwith increasing the degree value the shape "
                    "functions become smoother and the solution should become\nmore accurate but "
                    "that increases the solving time.",
                    url="https://en.wikipedia.org/wiki/Hp-FEM",
                    url_text="For more details click here"),
          unit="—", symbol="p", hint="≥ 1",
          error_msg="Must be a whole number other than 0."),
    Field("total_time", "Total time:", MESH,
          prm="set Total time", default_2d="1000", default_3d="1000",
          validate=_v_pos_int,
          info=Info("Total run time. If you do not know the exact time, write 1000. Thus the "
                    "solver \nwill automatically stop when it reaches to mechanical instability "
                    "point."),
          unit="wk", symbol="T", hint="1000 if unknown",
          error_msg="Must be a whole number other than 0."),
    Field("delt_t", "Time step size:", MESH,
          prm="set Time step size", default_2d="0.1", default_3d="0.1",
          validate=_v_delt_t,
          info=Info("Time step size, should take a value smaller than 1.0."),
          unit="wk", symbol=r"\Delta t", hint="0 < Δt < 1.0",
          error_msg="Must be greater than 0 and smaller than 1.0."),
    Field("stability_con", "Stabilization constant:", MESH,
          prm="set Stabilization constant", default_2d="0.0335", default_3d="0.0335",
          validate=_v_stability,
          info=Info("Stabilization constant Beta of advection-diffusion equation.\n"
                    "In this model, a numerical stabilization method is applied.\n"
                    "This value should be smaller than 0.1. The recommended value is 0.03334.",
                    url="https://www.dealii.org/current/doxygen/deal.II/step_31.html",
                    url_text="For more details click here"),
          unit="—", symbol=r"\beta", hint="≤ 0.1",
          error_msg="Must be smaller than or equal to 0.1."),
    Field("c_k", "c_k factor:", MESH,
          prm="set c_k factor", default_2d="0.33334", default_3d="0.33334",
          validate=_v_ck,
          info=Info("c_k factor that satisfies CFL condition, this value matter only in case of "
                    "Newton Raphson method not \nconverged. In this case, the solver repeat "
                    "solving the not converged time-step with considering \na smaller time-step "
                    "size according to the value of c_k.",
                    url="https://en.wikipedia.org/wiki/Courant%E2%80%93Friedrichs%E2%80%93Lewy_condition",
                    url_text="For more details click here"),
          unit="—", symbol="c_k", hint="≤ 1",
          error_msg="Must be smaller than or equal to 1."),

    # ---------------- Numerical solver ----------------
    Field("nonlinear_it", "Maximum Newton iterations:", SOLVER,
          prm="set Max number newton iterations", default_2d="8", default_3d="8",
          required=False, validate=_v_newton,
          info=Info("Max number of nonlinear iterations allowed.\nHere the Newton-Raphson method "
                    "is used to solve the nonlinear problem.",
                    url="https://en.wikipedia.org/wiki/Newton%27s_method",
                    url_text="For more details click here"),
          unit="—", symbol="n_{NR}", hint="≥ 3",
          error_msg="Must be 3 or greater."),
    Field("tol_u", "Tolerance residual deformation:", SOLVER,
          prm="set Tolerance residual deformation", default_2d="1.0e-8", default_3d="1.0e-8",
          required=False, validate=_v_tol,
          info=Info("Force residual error tolerance. The recommended value is 1.0e-8.\n"
                    "The smallest allowed value is 1.0e-4."),
          unit="—", symbol=r"tol_u", hint="≤ 1.0e-4",
          error_msg="Must be smaller than or equal to 1.0e-4."),
    Field("tol_c", "Tolerance residual cell density:", SOLVER,
          prm="set Tolerance residual diffusion", default_2d="1.0e-8", default_3d="1.0e-8",
          required=False, validate=_v_tol,
          info=Info("Advection-diffusion residual error tolerance. The recommended value is "
                    "1.0e-8.\nThe smallest allowed value is 1.0e-4."),
          unit="—", symbol=r"tol_c", hint="≤ 1.0e-4",
          error_msg="Must be smaller than or equal to 1.0e-4."),
    Field("update_u", "Tolerance update:", SOLVER,
          prm="set Tolerance update", default_2d="1.0e-4", default_3d="1.0e-4",
          required=False, validate=_v_tol_update,
          info=Info("Displacement & cell-density update error tolerance. The recommended value is "
                    "1.0e-4.\nThe smallest allowed value is 1.0e-3."),
          unit="—", symbol=r"tol_{up}", hint="≤ 1.0e-3",
          error_msg="Must be smaller than or equal to 1.0e-3."),
    Field("solver_type", "Linear solver type:", SOLVER,
          kind="radio", prm="set Linear solver type",
          options=[("Direct", "Direct"), ("CG", "CG")],
          default_2d="Direct", default_3d="Direct", required=False,
          info=Info("Type of solver used to solve the linear system.\nIn case of choosing CG "
                    "solver you should enter the number of linear solver iterations.",
                    url="https://en.wikipedia.org/wiki/Conjugate_gradient_method",
                    url_text="For more details click here"),
          unit="—", symbol="—", hint="Direct / CG"),
    Field("linear_it", "Iterations linear solver:", SOLVER,
          prm="set Multiplier max iterations linear solver", default_2d="", default_3d="",
          required=False,
          enabled_when=lambda v: v.get("solver_type") != "Direct",
          info=Info("The number of max iterations CG linear solver."),
          unit="—", symbol="n_{CG}", hint="CG only"),

    # ---------------- Growth ----------------
    Field("k_growth", "Growth rate:", GROWTH,
          prm="set Growth rate", default_2d="4.7e-4", default_3d="4.7e-5",
          validate=_v_k_growth,
          info=Info("Growth rate factor. This constant\ncoefficient controls the amount of\n"
                    "isotropic growth in the subcortical\nlayer. To serve numerical stability\n"
                    "requirements, this factor has to\nbe smaller than 1.0e-3 for the 2D\n"
                    "case and 1.0e-4 for the 3D case.",
                    img=("growth_eqautions_ks_light.png", "growth_eqautions_ks_dark.png")),
          unit="—", symbol="k_s", hint="2D ≤ 1e-3 · 3D ≤ 1e-4",
          error_msg="Exceeds the stability limit for this case."),
    Field("growth_ratio", "Growth ratio:", GROWTH,
          prm="set  Growth ratio",          # two spaces after "set" — matches Parameters.prm
          default_2d="1.5", default_3d="2",
          info=Info("Growth ratio. This ratio controls\nthe tangential and radial growth\n"
                    "amount in the cortical layer. With\nincreasing this value the growth\n"
                    "varying between tangential and\nradial growth increases.\n"
                    "The recommended value 1.5 and 3.",
                    img=("growth_eqautions_ratio_light.png", "growth_eqautions_ratio_dark.png")),
          unit="—", symbol="b", hint="1.5 – 3"),
    Field("growth_exp", "Growth exponent:", GROWTH,
          prm="set Growth exponent", default_2d="1.65", default_3d="1.65",
          info=Info("Growth exponent.",
                    img=("growth_eqautions_exp_light.png", "growth_eqautions_exp_dark.png")),
          unit="—", symbol=r"\alpha", hint="—"),
]

# Flat views used by the window and the .prm reader/writer.
ALL_FIELDS: list[Field] = FIELDS + [f for g in GROUPS.values() for f in g]
FIELDS_BY_KEY: dict[str, Field] = {f.key: f for f in ALL_FIELDS}
PRM_FIELDS: list[Field] = [f for f in ALL_FIELDS if f.prm]


# --- per-category identity: accent key + line-icon SVG path ------------------
# accent keys resolve to hex in bf_style.ACCENTS. Icons are 24x24 stroke paths.
SECTION_ACCENT: dict[str, str] = {
    GEOMETRY: "geo", DIFFUSION: "adv", STIFFNESS: "mech",
    MESH: "disc", SOLVER: "solv", GROWTH: "grow",
}
SECTION_ICON: dict[str, str] = {
    # Cube
    GEOMETRY:  '<path d="M12 2l9 5v10l-9 5-9-5V7z"/><path d="M12 12l9-5M12 12v10M12 12L3 7"/>',
    # Flowing lines
    DIFFUSION: '<path d="M3 8c3 0 3 3 6 3s3-3 6-3 3 3 6 3M3 15c3 0 3 3 6 3s3-3 6-3 3 3 6 3"/>',
    # Spring / coil
    STIFFNESS: '<path d="M2 12h2M20 12h2"/><path d="M4 12c0-4 2.7-4 2.7 0s2.7 4 2.7 0 2.7-4 2.7 0 2.7 4 2.7 0"/>',
    # Mesh / grid
    MESH:      '<rect x="4" y="4" width="16" height="16" rx="1"/><path d="M4 10h16M4 15h16M10 4v16M15 4v16"/>',
    # Sigma
    SOLVER:    '<path d="M17 5H7l6 7-6 7h10"/>',
    # Rising arrow / chart
    GROWTH:    '<path d="M3 17l6-6 4 4 8-8"/><path d="M21 11V7h-4"/>',
}

# Open-book icon for the Parameter Guide panel header.
GUIDE_ICON = ('<path d="M12 6C10 4.5 7 4.5 4 6v12c3-1.5 6-1.5 8 0 '
              '2-1.5 5-1.5 8 0V6c-3-1.5-6-1.5-8 0z"/><path d="M12 6v12"/>')
SECTION_SHORT: dict[str, str] = {
    GEOMETRY: "Geometry", DIFFUSION: "Advection–Diffusion", STIFFNESS: "Mechanical Properties",
    MESH: "Discretization", SOLVER: "Numerical Solver", GROWTH: "Growth",
}


# --- static info panels reachable from the buttons --------------------------
ABOUT_AUTHOR = Info(
    "Mohammad Saeed Zarzor\n\n"
    "- PhD candidate in the field of Biomechanics.\n"
    "- Scientific employee in Institute of Applied Mechanics,\n"
    "  Friedrich-Alexander-University Erlangen-Nürnberg.\n"
    "- Master of Science in Computational Engineering from FAU University.\n"
    "- Bachelor of Mechanical Engineering from Damascus University.",
    img=("my_photo.png", "my_photo.png"),
    url="https://www.ltm.tf.fau.eu/person/zarzor-mohammad-saeed-m-sc/", url_text="contact details")

ABOUT_PROGRAM = Info(
    "This work is part of the BRAINIACS Project at the Institute of Applied\n"
    "Mechanics, Friedrich-Alexander-University Erlangen-Nürnberg, under the\n"
    "supervision of Dr. Silvia Budday and in cooperation with Prof. Dr. med\n"
    "Ingmar Blümcke from Neuropathological Institute, University Hospitals\n"
    "Erlangen. We gratefully acknowledge the funding by the Deutsche\n"
    "Forschungsgemeinschaft (DFG, German Research Foundation).\n"
    "This work is based on the following paper:",
    img=("Logo_BRAINIACS.png", "Logo_BRAINIACS.png"),
    url="https://www.biorxiv.org/content/10.1101/2022.09.25.509401v1.abstract",
    url_text="Exploring the role of the outer subventricular zone during cortical folding through a physics-based model")

COPYRIGHT = Info(
    "The copyright holder for this preprint is the author/funder, who has granted bioRxiv a license\n"
    "to display the preprint in perpetuity. It is made available under a Copyright:",
    url="https://creativecommons.org/licenses/by/4.0/",
    url_text="CC-BY 4.0 International license.")

BACKGROUND = ("Untitled-3.png", "Untitled-3-dark.png")