navier-cfd 0.2.0__py3-none-any.whl

navier_cfd/__init__.py

@@ -0,0 +1,30 @@
+"""NAVIER-CFD public API: neural and agentic workflows for computational fluid dynamics."""
+
+from .catalogs import Catalog
+from .evidence import (
+    ALGORITHM_VERSION,
+    EvidenceMatch,
+    EvidenceRecord,
+    EvidenceSummary,
+    load_builtin_evidence,
+    score_model_evidence,
+)
+from .recommender import Recommendation, recommend_models
+from .specs import DatasetSpec, ModelSpec, TaskSpec
+
+__all__ = [
+    "ALGORITHM_VERSION",
+    "Catalog",
+    "DatasetSpec",
+    "EvidenceMatch",
+    "EvidenceRecord",
+    "EvidenceSummary",
+    "ModelSpec",
+    "Recommendation",
+    "TaskSpec",
+    "load_builtin_evidence",
+    "recommend_models",
+    "score_model_evidence",
+]
+
+__version__ = "0.2.0"

navier_cfd/__main__.py

@@ -0,0 +1,3 @@
+from .cli import app
+
+app()

navier_cfd/agents/__init__.py

@@ -0,0 +1,3 @@
+from .orchestrator import AgentOrchestrator, AgentPlan
+
+__all__ = ["AgentOrchestrator", "AgentPlan"]

navier_cfd/agents/orchestrator.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import asdict, dataclass
+from typing import Any, Protocol
+
+from ..benchmarks.planning import build_benchmark_plan
+from ..catalogs import Catalog
+from ..recommender import recommend_models
+from ..specs import TaskSpec
+
+
+class LLMBackend(Protocol):
+    def __call__(self, *, system: str, user: str, tools: list[dict[str, Any]]) -> dict[str, Any]: ...
+
+
+@dataclass
+class AgentPlan:
+    interpreted_task: TaskSpec
+    dataset_id: str
+    recommended_models: list[str]
+    benchmark_plan: dict[str, Any]
+    rationale: list[str]
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+class AgentOrchestrator:
+    """Provider-neutral experiment planner.
+
+    The deterministic planner works offline. A caller may inject any LLM backend that accepts
+    the documented structured interface; no vendor SDK is required by the core package.
+    """
+
+    def __init__(self, catalog: Catalog | None = None, backend: LLMBackend | None = None) -> None:
+        self.catalog = catalog or Catalog.load_builtin()
+        self.backend = backend
+
+    def plan(self, prompt: str) -> AgentPlan:
+        task, dataset_id = self._interpret(prompt)
+        recommendations = recommend_models(task, self.catalog.models, top_k=8)
+        dataset = self.catalog.dataset(dataset_id)
+        benchmark = build_benchmark_plan(task, dataset, recommendations)
+        rationale = [
+            f"Dataset selected from explicit or inferred benchmark: {dataset.name}.",
+            "Models were hard-filtered by dimension and mesh compatibility.",
+            "Ranking rewards task role, physics overlap, geometry/temporal support, and safety needs.",
+            "The emitted plan separates interpolation, OOD, stability, physics, and cost metrics.",
+        ]
+        return AgentPlan(
+            interpreted_task=task,
+            dataset_id=dataset_id,
+            recommended_models=[item.model.id for item in recommendations],
+            benchmark_plan=benchmark.to_dict(),
+            rationale=rationale,
+        )
+
+    def _interpret(self, prompt: str) -> tuple[TaskSpec, str]:
+        text = prompt.lower()
+        dataset_id = "pdebench"
+        if "realpdebench" in text or "real pde" in text or "sim-to-real" in text:
+            dataset_id = "realpdebench"
+        elif "cfdbench" in text or "cavity" in text or "dam" in text:
+            dataset_id = "cfdbench"
+
+        dimension = 3 if re.search(r"\b3d\b|three-dimensional", text) else 2
+        mesh = "unstructured" if "unstructured" in text else "structured"
+        temporal = "autoregressive" if any(k in text for k in ["rollout", "forecast", "unsteady", "sequence"]) else "steady"
+        geometry = "varying" if any(k in text for k in ["geometry", "shape", "airfoil", "vehicle", "wing"]) else "fixed"
+        task_type = "acceleration" if any(k in text for k in ["accelerat", "precondition", "corrector", "solver-in-the-loop"]) else "surrogate"
+        problem = "cylinder_wake" if "cylinder" in text else "general_cfd"
+        memory = None
+        match = re.search(r"(\d+(?:\.\d+)?)\s*gb", text)
+        if match:
+            memory = float(match.group(1))
+
+        physics = ["incompressible_navier_stokes"]
+        if "compressible" in text or "mach" in text or "shock" in text:
+            physics = ["compressible_navier_stokes"]
+        if "multiphase" in text or "dam" in text:
+            physics.append("multiphase")
+
+        task = TaskSpec(
+            problem=problem,
+            task_type=task_type,
+            dimension=dimension,
+            mesh_type=mesh,
+            temporal_mode=temporal,
+            geometry_mode=geometry,
+            physics=tuple(physics),
+            requires_conservation="conserv" in text or task_type == "acceleration",
+            requires_uncertainty="uncertainty" in text or "safe" in text or "certif" in text,
+            requires_geometry_transfer="geometry" in text or "shape" in text,
+            requires_mesh_transfer="mesh transfer" in text or "cross-mesh" in text,
+            requires_long_rollout=temporal == "autoregressive",
+            hardware_memory_gb=memory,
+            notes=prompt,
+        )
+        return task, dataset_id
+
+    @staticmethod
+    def tool_schemas() -> list[dict[str, Any]]:
+        return [
+            {"name": "list_datasets", "description": "List registered CFD/PDE datasets."},
+            {"name": "inspect_dataset", "description": "Read one dataset card."},
+            {"name": "recommend_models", "description": "Rank compatible neural solvers."},
+            {"name": "build_benchmark_plan", "description": "Create splits, metrics and ablations."},
+            {"name": "emit_run_manifest", "description": "Serialize a reproducible experiment plan."},
+        ]
+
+    def plan_json(self, prompt: str) -> str:
+        return json.dumps(self.plan(prompt).to_dict(), indent=2)

navier_cfd/benchmarks/__init__.py

@@ -0,0 +1,4 @@
+from .metrics import compute_metric_bundle
+from .planning import BenchmarkPlan, build_benchmark_plan
+
+__all__ = ["BenchmarkPlan", "build_benchmark_plan", "compute_metric_bundle"]

navier_cfd/benchmarks/metrics.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+
+def rmse(pred: np.ndarray, target: np.ndarray) -> float:
+    return float(np.sqrt(np.mean((pred - target) ** 2)))
+
+
+def mae(pred: np.ndarray, target: np.ndarray) -> float:
+    return float(np.mean(np.abs(pred - target)))
+
+
+def relative_l2(pred: np.ndarray, target: np.ndarray, eps: float = 1e-12) -> float:
+    return float(np.linalg.norm(pred - target) / (np.linalg.norm(target) + eps))
+
+
+def r2(pred: np.ndarray, target: np.ndarray, eps: float = 1e-12) -> float:
+    residual = np.sum((target - pred) ** 2)
+    total = np.sum((target - np.mean(target)) ** 2)
+    return float(1.0 - residual / (total + eps))
+
+
+def spectral_relative_error(pred: np.ndarray, target: np.ndarray, eps: float = 1e-12) -> float:
+    axes = tuple(range(-min(2, pred.ndim), 0))
+    p = np.abs(np.fft.rfftn(pred, axes=axes))
+    t = np.abs(np.fft.rfftn(target, axes=axes))
+    return float(np.linalg.norm(p - t) / (np.linalg.norm(t) + eps))
+
+
+def divergence_rms(velocity: np.ndarray, spacing: tuple[float, ...] | None = None) -> float:
+    """Approximate RMS divergence for arrays shaped (..., spatial..., components)."""
+    if velocity.shape[-1] not in {2, 3}:
+        raise ValueError("velocity must store 2 or 3 components in the final axis")
+    ncomp = velocity.shape[-1]
+    spacing = spacing or tuple(1.0 for _ in range(ncomp))
+    if len(spacing) != ncomp:
+        raise ValueError("spacing length must equal the number of velocity components")
+    div = 0.0
+    for component in range(ncomp):
+        axis = velocity.ndim - ncomp - 1 + component
+        div = div + np.gradient(velocity[..., component], spacing[component], axis=axis)
+    return float(np.sqrt(np.mean(np.asarray(div) ** 2)))
+
+
+def compute_metric_bundle(
+    pred: np.ndarray,
+    target: np.ndarray,
+    *,
+    velocity: bool = False,
+    spacing: tuple[float, ...] | None = None,
+) -> dict[str, Any]:
+    pred = np.asarray(pred)
+    target = np.asarray(target)
+    if pred.shape != target.shape:
+        raise ValueError(f"shape mismatch: {pred.shape} != {target.shape}")
+    metrics: dict[str, Any] = {
+        "rmse": rmse(pred, target),
+        "mae": mae(pred, target),
+        "relative_l2": relative_l2(pred, target),
+        "r2": r2(pred, target),
+        "spectral_relative_error": spectral_relative_error(pred, target),
+    }
+    if velocity:
+        metrics["divergence_rms_pred"] = divergence_rms(pred, spacing)
+        metrics["divergence_rms_target"] = divergence_rms(target, spacing)
+    return metrics

navier_cfd/benchmarks/planning.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+from ..recommender import Recommendation
+from ..specs import DatasetSpec, TaskSpec
+
+
+@dataclass
+class BenchmarkPlan:
+    task: TaskSpec
+    dataset: DatasetSpec
+    models: list[str]
+    splits: list[str]
+    metrics: list[str]
+    ablations: list[str]
+    reporting: list[str]
+    created_at: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def build_benchmark_plan(
+    task: TaskSpec,
+    dataset: DatasetSpec,
+    recommendations: list[Recommendation],
+    max_models: int = 6,
+) -> BenchmarkPlan:
+    metrics = [
+        "relative_l2",
+        "rmse",
+        "mae",
+        "r2",
+        "spectral_relative_error",
+        "wall_clock",
+        "peak_memory",
+    ]
+    if task.temporal_mode in {"autoregressive", "unsteady", "sequence"}:
+        metrics += ["stable_horizon", "rollout_drift", "autocorrelation_error"]
+    if task.requires_conservation:
+        metrics += ["mass_balance_error", "momentum_balance_error", "divergence_rms"]
+    if task.requires_uncertainty:
+        metrics += ["coverage", "calibration_error", "risk_coverage"]
+
+    splits = ["interpolation", "parameter_ood"]
+    if task.requires_geometry_transfer or task.geometry_mode == "varying":
+        splits.append("geometry_ood")
+    if task.requires_mesh_transfer:
+        splits += ["mesh_resolution_ood", "mesh_generator_ood"]
+    if "real" in dataset.name.lower() or "real" in dataset.description.lower():
+        splits.append("sim_to_real")
+
+    return BenchmarkPlan(
+        task=task,
+        dataset=dataset,
+        models=[item.model.id for item in recommendations[:max_models]],
+        splits=splits,
+        metrics=list(dict.fromkeys(metrics)),
+        ablations=[
+            "remove_physics_features",
+            "remove_geometry_features",
+            "one_step_vs_unrolled_training",
+            "matched_parameter_and_wall_clock_budget",
+        ],
+        reporting=[
+            "three_or_more_random_seeds",
+            "confidence_intervals_over_cases",
+            "data_generation_cost",
+            "training_cost",
+            "break_even_query_count",
+            "pinned_dataset_and_model_revisions",
+        ],
+    )

navier_cfd/catalogs.py

@@ -0,0 +1,208 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable
+import json
+
+from .specs import DatasetSpec, ModelSpec
+
+_MODEL_ROWS = [
+    ("pinn", "Physics-Informed Neural Network", ("physics_informed", "general_pde_solver", "inverse")),
+    ("nsfnets", "NSFnets", ("physics_informed", "specialized")),
+    ("pinnsformer", "PINNsFormer", ("physics_informed", "general_pde_solver")),
+    ("deeponet", "DeepONet", ("surrogate", "general_pde_solver", "physics_informed")),
+    ("mionet", "MIONet", ("surrogate", "general_pde_solver")),
+    ("fourier_deeponet", "Fourier-DeepONet", ("surrogate", "specialized")),
+    ("nested_fourier_deeponet", "Nested Fourier-DeepONet", ("surrogate", "specialized", "particle_multiphase")),
+    ("fourier_mionet", "Fourier-MIONet", ("surrogate", "specialized", "particle_multiphase")),
+    ("fno", "Fourier Neural Operator", ("surrogate", "general_pde_solver")),
+    ("pino", "Physics-Informed Neural Operator", ("physics_informed", "surrogate", "general_pde_solver")),
+    ("geo_fno", "Geo-FNO", ("geometry", "surrogate", "general_pde_solver")),
+    ("gino", "Geometry-Informed Neural Operator", ("geometry", "surrogate")),
+    ("u_fno", "U-FNO", ("surrogate", "specialized", "particle_multiphase")),
+    ("f_fno", "Factorized FNO", ("surrogate", "general_pde_solver")),
+    ("u_no", "U-shaped Neural Operator", ("surrogate", "general_pde_solver")),
+    ("lsm", "Latent Spectral Model", ("surrogate", "general_pde_solver")),
+    ("gnot", "General Neural Operator Transformer", ("surrogate", "general_pde_solver", "geometry")),
+    ("galerkin_transformer", "Galerkin Transformer", ("surrogate", "general_pde_solver")),
+    ("mwt", "Multiwavelet Transformer", ("surrogate", "general_pde_solver")),
+    ("factformer", "FactFormer", ("surrogate", "general_pde_solver")),
+    ("ono", "Orthogonal Neural Operator", ("surrogate", "general_pde_solver")),
+    ("transolver", "Transolver", ("geometry", "surrogate", "general_pde_solver")),
+    ("upt", "Universal Physics Transformer", ("foundation", "geometry", "surrogate", "general_pde_solver")),
+    ("meshgraphnets", "MeshGraphNets", ("geometry", "surrogate")),
+    ("domino", "DoMINO", ("geometry", "surrogate", "specialized")),
+    ("pibert", "PIBERT", ("surrogate", "physics_informed", "specialized")),
+    ("fourierflow", "FourierFlow", ("surrogate", "generative", "specialized")),
+    ("pde_refiner", "PDE-Refiner", ("surrogate", "generative", "general_pde_solver")),
+    ("dpot", "DPOT", ("foundation", "surrogate", "general_pde_solver")),
+    ("poseidon", "Poseidon", ("foundation", "surrogate", "general_pde_solver")),
+    ("prose_fd", "PROSE-FD", ("foundation", "surrogate", "specialized")),
+    ("bcat", "BCAT", ("foundation", "surrogate", "specialized")),
+    ("pdeformer1", "PDEformer-1", ("foundation", "general_pde_solver")),
+    ("pi_mfm", "PI-MFM", ("foundation", "physics_informed", "general_pde_solver")),
+    ("laplace_no", "Laplace Neural Operator", ("surrogate", "general_pde_solver")),
+    ("state_space_no", "State-Space Neural Operator", ("surrogate", "general_pde_solver")),
+    ("p3d", "P3D", ("surrogate", "foundation", "specialized")),
+    ("aerotransformer", "AeroTransformer", ("foundation", "geometry", "specialized")),
+    ("tadpole", "Tadpole", ("foundation", "surrogate")),
+    ("solver_in_loop", "Solver-in-the-Loop", ("acceleration", "physics_informed")),
+    ("inc", "Indirect Neural Corrector", ("acceleration", "physics_informed")),
+    ("pict", "PICT", ("acceleration", "specialized", "physics_informed")),
+    ("diffsph", "diffSPH", ("acceleration", "particle_multiphase", "specialized")),
+    ("neurosem", "NeuroSEM", ("acceleration", "physics_informed", "specialized")),
+    ("np_newton", "Neural-Operator Preconditioned Newton", ("acceleration", "general_pde_solver")),
+    ("geometry_preconditioner", "Geometry-Aware Neural Preconditioner", ("acceleration", "geometry")),
+    ("neuraldem", "NeuralDEM", ("specialized", "particle_multiphase", "surrogate")),
+    ("revit", "ReViT", ("geometry", "surrogate")),
+    ("deepmmnet", "DeepM&Mnet", ("surrogate", "specialized", "physics_informed")),
+    ("conformal_deeponet", "Conformalized-DeepONet", ("uncertainty", "surrogate")),
+    ("tante", "TANTE", ("surrogate", "general_pde_solver")),
+    ("riemannonet", "RiemannONet", ("physics_informed", "specialized", "surrogate")),
+    ("energy_transformer", "Energy Transformer Flow Reconstruction", ("inverse", "surrogate", "specialized")),
+    ("fun_diff", "FunDiff", ("generative", "physics_informed", "general_pde_solver")),
+    ("flow_matching_pde", "Flow Matching for PDEs", ("generative", "physics_informed", "general_pde_solver")),
+]
+
+_GEOMETRY = {"geo_fno", "gino", "gnot", "transolver", "upt", "meshgraphnets", "domino", "aerotransformer", "geometry_preconditioner", "revit"}
+_THREED = {"gino", "upt", "domino", "p3d", "aerotransformer", "tadpole", "inc", "pict", "diffsph", "neurosem", "np_newton", "geometry_preconditioner", "neuraldem", "revit", "deepmmnet", "tante", "energy_transformer"}
+_ACCEL = {"solver_in_loop", "inc", "pict", "diffsph", "neurosem", "np_newton", "geometry_preconditioner"}
+_LONG = {"pinnsformer", "fno", "f_fno", "pibert", "fourierflow", "pde_refiner", "dpot", "poseidon", "prose_fd", "bcat", "p3d", "tadpole", "solver_in_loop", "inc", "neuraldem", "tante"}
+_PARTICLE = {"diffsph", "neuraldem"}
+_UQ = {"conformal_deeponet", "fun_diff", "fourierflow"}
+
+_ARCH = {
+    "pinn": "coordinate network with PDE residuals",
+    "deeponet": "branch-trunk operator network",
+    "fno": "Fourier neural operator",
+    "pibert": "bidirectional transformer with Fourier-wavelet embeddings and physics-biased attention",
+    "fourierflow": "frequency-guided generative flow model",
+    "transolver": "physics-attention transformer on general geometries",
+    "upt": "latent universal physics transformer",
+    "gino": "graph lifting, latent FNO, and point projection",
+    "domino": "decomposable multiscale iterative neural operator",
+    "p3d": "scalable 3D global-context surrogate",
+    "aerotransformer": "pretrained transformer for 3D aerodynamics",
+    "inc": "equation-level indirect neural corrector",
+    "pict": "differentiable GPU multi-block PISO solver",
+    "diffsph": "differentiable smoothed-particle hydrodynamics",
+    "np_newton": "neural-operator preconditioned Newton solver",
+    "geometry_preconditioner": "geometry-aware neural iterative preconditioner",
+}
+
+_REF = {
+    "pibert": "Chakraborty, Pan & Chen, 2026",
+    "fno": "Li et al., ICLR 2021",
+    "deeponet": "Lu et al., Nature Machine Intelligence 2021",
+    "transolver": "Wu et al., ICML 2024",
+    "upt": "Alkin et al., NeurIPS 2024",
+    "gino": "Li et al., NeurIPS 2023",
+    "inc": "Wei et al., NeurIPS 2025",
+    "pict": "Franz et al., JCP 2025",
+    "diffsph": "Winchenbach & Thuerey, JCP 2026",
+}
+
+_REPO = {
+    "pibert": "https://github.com/Samsomyajit/pibert",
+    "fno": "https://github.com/neuraloperator/neuraloperator",
+    "geo_fno": "https://github.com/neuraloperator/Geo-FNO",
+    "transolver": "https://github.com/thuml/Neural-Solver-Library",
+    "inc": "https://github.com/tum-pbs/INC",
+}
+
+
+def _models() -> list[ModelSpec]:
+    result: list[ModelSpec] = []
+    for model_id, name, categories in _MODEL_ROWS:
+        geometry = model_id in _GEOMETRY
+        three_d = model_id in _THREED or model_id not in {"pinnsformer", "riemannonet"}
+        accel = model_id in _ACCEL
+        particle = model_id in _PARTICLE
+        mesh_types = ("particle",) if particle else (("unstructured", "point_cloud", "structured") if geometry else ("structured", "meshfree"))
+        result.append(ModelSpec(
+            id=model_id,
+            name=name,
+            categories=categories,
+            architecture=_ARCH.get(model_id, name + " architecture"),
+            tasks=(("acceleration", "corrector", "preconditioner") if accel else ("surrogate", "forecasting")),
+            physics=(("particle", "granular") if particle else ("general_pde", "fluid_dynamics")),
+            mesh_types=mesh_types,
+            geometry_modes=(("varying", "parameterized") if geometry else ("fixed", "parameterized")),
+            temporal_modes=(("autoregressive", "unsteady", "steady") if model_id in _LONG or accel else ("steady", "unsteady")),
+            dimensions=((1, 2, 3) if three_d else (1, 2)),
+            strengths=("registered in the uniform NAVIER-CFD model taxonomy",),
+            limitations=("verify claims on the selected CFD benchmark and discretization",),
+            reference=_REF.get(model_id, name),
+            repository=_REPO.get(model_id),
+            integration="external" if model_id in _REPO else "metadata",
+            min_memory_gb=24 if model_id in {"gino", "domino", "p3d", "aerotransformer", "neuraldem"} else 8,
+            framework="pytorch",
+            tags=tuple(filter(None, ["mesh_transfer" if geometry else "", "long_rollout" if model_id in _LONG or accel else "", "uncertainty" if model_id in _UQ else "", "conservative" if accel else "", "3d" if three_d else ""])),
+        ))
+    return result
+
+
+def _datasets() -> list[DatasetSpec]:
+    rows = [
+        ("pdebench", "PDEBench", "Extensive time-dependent PDE benchmark", "AI4Science-WestlakeU/PDEBench", ("navier_stokes", "advection", "reaction_diffusion"), (1, 2, 3), ("structured",), ("fixed",), ("autoregressive",)),
+        ("cfdbench", "CFDBench", "CFD benchmark with boundary, property, and geometry shifts", "chen-yingfa/CFDBench", ("cavity", "tube", "dam", "cylinder"), (2,), ("structured",), ("fixed", "varying"), ("steady", "autoregressive")),
+        ("realpdebench", "RealPDEBench", "Paired real-world and simulated spatiotemporal systems", "AI4Science-WestlakeU/RealPDEBench", ("cylinder", "fsi", "controlled_cylinder", "foil", "combustion"), (2,), ("structured",), ("fixed", "varying"), ("autoregressive",)),
+        ("airfrans", "AirfRANS", "RANS airfoil geometry and operating-condition benchmark", None, ("airfoil",), (2,), ("unstructured", "point_cloud"), ("varying",), ("steady",)),
+        ("drivaernetpp", "DrivAerNet++", "Large multimodal vehicle CFD dataset", None, ("vehicle_aerodynamics",), (3,), ("point_cloud", "unstructured"), ("varying",), ("steady",)),
+        ("drivaerml", "DrivAerML", "High-fidelity road-car aerodynamic CFD", None, ("vehicle_aerodynamics",), (3,), ("unstructured",), ("varying",), ("steady", "unsteady")),
+        ("the_well", "The Well", "Diverse large-scale physics simulations", "polymathic-ai/the_well", ("fluid", "multiphysics"), (2, 3), ("structured",), ("fixed", "varying"), ("autoregressive",)),
+        ("apebench", "APEBench", "Autoregressive PDE emulator benchmark", None, ("46_pde_configurations",), (1, 2, 3), ("structured",), ("fixed",), ("autoregressive",)),
+        ("scalarflow", "ScalarFlow", "Real volumetric scalar transport flows", None, ("scalar_transport",), (3,), ("structured",), ("fixed",), ("autoregressive",)),
+        ("shapenet_car", "ShapeNet-Car", "Vehicle-shape design benchmark", None, ("vehicle_design",), (3,), ("point_cloud",), ("varying",), ("steady",)),
+        ("eagle", "EAGLE", "Fluid and geometry learning benchmark", None, ("fluid",), (2, 3), ("structured", "unstructured"), ("varying",), ("autoregressive",)),
+    ]
+    return [DatasetSpec(
+        id=i, name=n, description=d, tasks=("surrogate", "benchmark"), physics=("fluid_dynamics", "general_pde"),
+        dimensions=dim, mesh_types=mesh, geometry_modes=geo, temporal_modes=temp,
+        hf_repo_id=hf, source_url=None, license=None, size=None, scenarios=scenarios,
+        notes=("Pin dataset revisions and preserve official splits.",)
+    ) for i, n, d, hf, scenarios, dim, mesh, geo, temp in rows]
+
+
+@dataclass
+class Catalog:
+    models: list[ModelSpec]
+    datasets: list[DatasetSpec]
+
+    @classmethod
+    def load_builtin(cls) -> "Catalog":
+        return cls(models=_models(), datasets=_datasets())
+
+    @classmethod
+    def from_paths(cls, model_path: str | Path, dataset_path: str | Path) -> "Catalog":
+        model_data = json.loads(Path(model_path).read_text(encoding="utf-8"))
+        dataset_data = json.loads(Path(dataset_path).read_text(encoding="utf-8"))
+        return cls([ModelSpec.from_dict(x) for x in model_data], [DatasetSpec.from_dict(x) for x in dataset_data])
+
+    def model(self, model_id: str) -> ModelSpec:
+        for item in self.models:
+            if item.id == model_id:
+                return item
+        raise KeyError(f"Unknown model id: {model_id}")
+
+    def dataset(self, dataset_id: str) -> DatasetSpec:
+        for item in self.datasets:
+            if item.id == dataset_id:
+                return item
+        raise KeyError(f"Unknown dataset id: {dataset_id}")
+
+    def models_by_category(self, category: str) -> list[ModelSpec]:
+        return [x for x in self.models if category in x.categories]
+
+    def search_models(self, query: str) -> list[ModelSpec]:
+        q = query.lower()
+        return [x for x in self.models if q in x.name.lower() or q in x.architecture.lower() or any(q in t.lower() for t in x.tags)]
+
+    def extend_models(self, models: Iterable[ModelSpec]) -> None:
+        existing = {x.id for x in self.models}
+        for model in models:
+            if model.id in existing:
+                raise ValueError(f"Duplicate model id: {model.id}")
+            self.models.append(model)
+            existing.add(model.id)