flowgraph 0.1.6__tar.gz → 0.1.7__tar.gz

{flowgraph-0.1.6/src/flowgraph.egg-info → flowgraph-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowgraph
-Version: 0.1.6
+Version: 0.1.7
 Summary: Headless typed workflow engine and execution runtime
 Author: Felipe Bordeu
 Maintainer: Felipe Bordeu
@@ -61,7 +61,14 @@ for compatible external clients.
 > development, experimentation, and early adopter feedback. APIs and workflow
 > behavior may change before `1.0.0`. See [`Release Policy`](docs/policies/release-policy.md).
 
-## Development
+## Incremental workflow execution
+
+`WorkflowExecutor` remains stateless. Use `WorkflowSession` for selected targets,
+dependency-aware cache reuse, forced runs and session lifecycle. See
+[`Incremental execution`](doc/reference/incremental-execution.md) for the Python
+API, node safety contracts, transport options and resource limits.
+
+## Development setup
 
 ```bash
 uv sync --extra dev
@@ -107,6 +114,52 @@ For examples and warning output, see
 Workflows use the versioned `flowgraph-workflow` JSON format. Core validation and
 execution are UI-independent.
 
+### JSON execution boundary
+
+Python clients and browser-hosted Python workers use the same entry point:
+
+```python
+from flowgraph.application.workflow_execution import execute_workflow_json
+
+result_json = execute_workflow_json(workflow_json)
+```
+
+The response includes execution order, public outputs, retained node values,
+display previews, warnings, and structured errors. A process-local node registry
+is reused, but each call reconstructs its workflow. This API does not provide a
+server, authentication, cancellation, or filesystem isolation.
+
+Mesh display previews retain scalar values or vector magnitudes in `fields` and
+`cell_fields`. Multi-component fields additionally expose their original tuples
+in `field_components` and `cell_field_components`, indexed by vertex or surface
+triangle respectively, so viewers can select an individual component without
+rerunning the workflow. These preview projections do not modify the input mesh.
+
+The former WASM-specific execution module has been removed without a compatibility
+alias. Browser clients must update their import and rebuild/stage their core wheel
+together; the workflow file and execution response formats are unchanged.
+
+## Experimental local server
+
+The prototype branch includes an authenticated, loopback-only execution API:
+
+```bash
+uv run flowgraph serve --workspace /absolute/path/to/existing/workspace
+```
+
+Port 8765 and the allowed editor origin `https://flowgraph-web.fbw-es.com` are
+defaults; explicit `--allow-origin` values replace that origin. The editor still
+requires bearer authentication and browser local-network permission. Click the
+printed **Open editor** link to pass the token and port automatically; keep the
+link private.
+
+It runs one workflow at a time in a cancellable native subprocess and provides
+runtime metadata, catalog, and workspace file endpoints. Core is API-only and never
+serves editor assets. Web and desktop clients own their GUI hosting and explicitly
+allow their origin with `--allow-origin`. Native workflow code is **not sandboxed**.
+See [Local server API and limitations](docs/local-server.md) for authentication,
+request/response formats, examples, limits, and shutdown behavior.
+
 ## Package artifacts
 
 Build the portable, pure-Python source distribution and wheel with:
@@ -129,7 +182,7 @@ Docker, operating-system package managers, and third-party mirrors are not
 supported release channels at this time. See
 [`Release Channels`](docs/policies/release-channels.md) for the release policy.
 
-FlowGraph Core declares Python 3.11 or newer. CI covers Python 3.11 and 3.13 on
+FlowGraph Core declares Python 3.11 or newer. CI covers Python 3.11, 3.12, 3.13, and 3.14 on
 GitHub-hosted Ubuntu, Windows, and macOS runners; a platform/version combination
 is supported only after its release-candidate job passes. See
 [`Support Policy`](docs/policies/support-policy.md) for compatibility, deprecation,

{flowgraph-0.1.6 → flowgraph-0.1.7}/README.md

@@ -9,7 +9,14 @@ for compatible external clients.
 > development, experimentation, and early adopter feedback. APIs and workflow
 > behavior may change before `1.0.0`. See [`Release Policy`](docs/policies/release-policy.md).
 
-## Development
+## Incremental workflow execution
+
+`WorkflowExecutor` remains stateless. Use `WorkflowSession` for selected targets,
+dependency-aware cache reuse, forced runs and session lifecycle. See
+[`Incremental execution`](doc/reference/incremental-execution.md) for the Python
+API, node safety contracts, transport options and resource limits.
+
+## Development setup
 
 ```bash
 uv sync --extra dev
@@ -55,6 +62,52 @@ For examples and warning output, see
 Workflows use the versioned `flowgraph-workflow` JSON format. Core validation and
 execution are UI-independent.
 
+### JSON execution boundary
+
+Python clients and browser-hosted Python workers use the same entry point:
+
+```python
+from flowgraph.application.workflow_execution import execute_workflow_json
+
+result_json = execute_workflow_json(workflow_json)
+```
+
+The response includes execution order, public outputs, retained node values,
+display previews, warnings, and structured errors. A process-local node registry
+is reused, but each call reconstructs its workflow. This API does not provide a
+server, authentication, cancellation, or filesystem isolation.
+
+Mesh display previews retain scalar values or vector magnitudes in `fields` and
+`cell_fields`. Multi-component fields additionally expose their original tuples
+in `field_components` and `cell_field_components`, indexed by vertex or surface
+triangle respectively, so viewers can select an individual component without
+rerunning the workflow. These preview projections do not modify the input mesh.
+
+The former WASM-specific execution module has been removed without a compatibility
+alias. Browser clients must update their import and rebuild/stage their core wheel
+together; the workflow file and execution response formats are unchanged.
+
+## Experimental local server
+
+The prototype branch includes an authenticated, loopback-only execution API:
+
+```bash
+uv run flowgraph serve --workspace /absolute/path/to/existing/workspace
+```
+
+Port 8765 and the allowed editor origin `https://flowgraph-web.fbw-es.com` are
+defaults; explicit `--allow-origin` values replace that origin. The editor still
+requires bearer authentication and browser local-network permission. Click the
+printed **Open editor** link to pass the token and port automatically; keep the
+link private.
+
+It runs one workflow at a time in a cancellable native subprocess and provides
+runtime metadata, catalog, and workspace file endpoints. Core is API-only and never
+serves editor assets. Web and desktop clients own their GUI hosting and explicitly
+allow their origin with `--allow-origin`. Native workflow code is **not sandboxed**.
+See [Local server API and limitations](docs/local-server.md) for authentication,
+request/response formats, examples, limits, and shutdown behavior.
+
 ## Package artifacts
 
 Build the portable, pure-Python source distribution and wheel with:
@@ -77,7 +130,7 @@ Docker, operating-system package managers, and third-party mirrors are not
 supported release channels at this time. See
 [`Release Channels`](docs/policies/release-channels.md) for the release policy.
 
-FlowGraph Core declares Python 3.11 or newer. CI covers Python 3.11 and 3.13 on
+FlowGraph Core declares Python 3.11 or newer. CI covers Python 3.11, 3.12, 3.13, and 3.14 on
 GitHub-hosted Ubuntu, Windows, and macOS runners; a platform/version combination
 is supported only after its release-candidate job passes. See
 [`Support Policy`](docs/policies/support-policy.md) for compatibility, deprecation,

{flowgraph-0.1.6 → flowgraph-0.1.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "flowgraph"
-version = "0.1.6"
+version = "0.1.7"
 description = "Headless typed workflow engine and execution runtime"
 readme = "README.md"
 requires-python = ">=3.11"

{flowgraph-0.1.6 → flowgraph-0.1.7}/src/flowgraph/adapters/__init__.py

@@ -5,6 +5,7 @@ from dataclasses import dataclass
 from flowgraph.adapters.controls import AVAILABLE_NODES as CONTROL_AVAILABLE_NODES
 from flowgraph.adapters.cosapp import AVAILABLE_NODES as COSAPP_AVAILABLE_NODES
 from flowgraph.adapters.documentation import AVAILABLE_NODES as DOCUMENTATION_AVAILABLE_NODES
+from flowgraph.adapters.field_gradient import SCALAR_FIELD_GRADIENT, VECTOR_FIELD_GRADIENT
 from flowgraph.adapters.field_ops import AVAILABLE_NODES as FIELD_OPS_AVAILABLE_NODES
 from flowgraph.adapters.file_conversion import MESH_FILE_CONVERSION
 from flowgraph.adapters.files import (
@@ -14,13 +15,18 @@ from flowgraph.adapters.files import (
 )
 from flowgraph.adapters.filters import (
     CREATE_MUSCAT_ELEMENT_FILTER,
+    CREATE_MUSCAT_NODE_FILTER,
     FILTER_MESH_WITH_MUSCAT,
+    SELECTOR_OPERATORS,
 )
 from flowgraph.adapters.image_tools import AVAILABLE_NODES as IMAGE_TOOLS_AVAILABLE_NODES
 from flowgraph.adapters.imagej import AVAILABLE_NODES as IMAGEJ_AVAILABLE_NODES
+from flowgraph.adapters.mesh_analysis import MESH_NODES, SET_MESH_FIELD
+from flowgraph.adapters.mesh_composition import FIELD_COMPOSITION_NODES, MESH_COMPOSITION_NODES
 from flowgraph.adapters.mesh_creation_tools import AVAILABLE_NODES as MESH_CREATION_AVAILABLE_NODES
 from flowgraph.adapters.mesh_generations import CSV_TO_MESH
 from flowgraph.adapters.mesh_ops import AVAILABLE_NODES as MESH_OPS_AVAILABLE_NODES
+from flowgraph.adapters.paraview import PARAVIEW_BRIDGE
 from flowgraph.adapters.plaid_bridge import AVAILABLE_NODES as PLAID_AVAILABLE_NODES
 from flowgraph.adapters.readers import (
     LOAD_CSV,
@@ -31,10 +37,10 @@ from flowgraph.adapters.readers import (
 )
 from flowgraph.adapters.remote_files import DOWNLOAD_URL
 from flowgraph.adapters.simple_sources import (
+    SET_ARRAY_1D,
     SET_BOOLEAN,
     SET_FLOAT,
     SET_INT,
-    SET_LIST_FLOAT,
     SET_LIST_INT,
     SET_LIST_STR,
     SET_STRING,
@@ -45,11 +51,13 @@ from flowgraph.adapters.simple_sources import (
 from flowgraph.adapters.sinks import AVAILABLE_NODES as SINKS_AVAILABLE_NODES
 from flowgraph.adapters.table_tools import AVAILABLE_NODES as TABLE_TOOLS_AVAILABLE_NODES
 from flowgraph.adapters.user_code import AVAILABLE_NODES as USER_CODE_AVAILABLE_NODES
+from flowgraph.adapters.vector_tools import AVAILABLE_NODES as VECTOR_TOOLS_AVAILABLE_NODES
 from flowgraph.adapters.workflow import AVAILABLE_NODES as WORKFLOW_AVAILABLE_NODES
 from flowgraph.adapters.workflow_interfaces import (
     AVAILABLE_NODES as WORKFLOW_INTERFACE_AVAILABLE_NODES,
 )
 from flowgraph.adapters.writers import WRITE_MESHIO, WRITE_MESHLANE, WRITE_MUSCAT, WRITE_TABLE
+from flowgraph.adapters.zones import AVAILABLE_NODES as ZONE_AVAILABLE_NODES
 from flowgraph.application.workflow_core import NodeDefinition
 
 
@@ -99,10 +107,13 @@ ADAPTERS = AdapterCatalog(
         AdapterGroup(
             "Inputs",
             subgroups=(
-                AdapterGroup("Scalars", (SET_STRING, SET_BOOLEAN, SET_INT, SET_FLOAT)),
+                AdapterGroup(
+                    "Scalars",
+                    (SET_STRING, SET_BOOLEAN, SET_INT, SET_FLOAT) + CONTROL_AVAILABLE_NODES,
+                ),
                 AdapterGroup(
                     "Lists/Vectors",
-                    (SET_LIST_STR, SET_LIST_INT, SET_LIST_FLOAT, SET_VEC2D, SET_VEC2DI, SET_VEC3D),
+                    (SET_LIST_STR, SET_LIST_INT, SET_ARRAY_1D, SET_VEC2D, SET_VEC2DI, SET_VEC3D),
                 ),
                 AdapterGroup(
                     "Files",
@@ -117,24 +128,36 @@ ADAPTERS = AdapterCatalog(
                     "Readers",
                     (LOAD_MUSCAT, LOAD_MESHIO, LOAD_MESHLANE, LOAD_CSV, READ_TABLE),
                 ),
-                AdapterGroup("Mesh Gens", (CSV_TO_MESH,)),
-                AdapterGroup("Mesh Creation", MESH_CREATION_AVAILABLE_NODES),
+                AdapterGroup("Mesh Creation", (CSV_TO_MESH,) + MESH_CREATION_AVAILABLE_NODES),
                 AdapterGroup(
                     "Filters",
-                    (CREATE_MUSCAT_ELEMENT_FILTER, FILTER_MESH_WITH_MUSCAT),
+                    (
+                        CREATE_MUSCAT_ELEMENT_FILTER,
+                        CREATE_MUSCAT_NODE_FILTER,
+                        FILTER_MESH_WITH_MUSCAT,
+                    )
+                    + SELECTOR_OPERATORS,
+                    subgroups=(AdapterGroup("Zones", ZONE_AVAILABLE_NODES),),
+                ),
+                AdapterGroup(
+                    "Mesh Ops", MESH_OPS_AVAILABLE_NODES + MESH_NODES + MESH_COMPOSITION_NODES
+                ),
+                AdapterGroup(
+                    "Field Ops",
+                    FIELD_OPS_AVAILABLE_NODES
+                    + (SET_MESH_FIELD, SCALAR_FIELD_GRADIENT, VECTOR_FIELD_GRADIENT)
+                    + FIELD_COMPOSITION_NODES,
                 ),
-                AdapterGroup("Mesh Ops", MESH_OPS_AVAILABLE_NODES),
-                AdapterGroup("Field Ops", FIELD_OPS_AVAILABLE_NODES),
                 AdapterGroup("File Conversion", (MESH_FILE_CONVERSION,)),
                 AdapterGroup("Writers", (WRITE_MUSCAT, WRITE_MESHLANE, WRITE_MESHIO, WRITE_TABLE)),
             ),
         ),
-        AdapterGroup("Controls", CONTROL_AVAILABLE_NODES),
         AdapterGroup("Image Tools", IMAGE_TOOLS_AVAILABLE_NODES),
         AdapterGroup("Table Tools", TABLE_TOOLS_AVAILABLE_NODES),
+        AdapterGroup("Vector Tools", VECTOR_TOOLS_AVAILABLE_NODES),
         AdapterGroup("Code", USER_CODE_AVAILABLE_NODES + IMAGEJ_AVAILABLE_NODES),
         AdapterGroup("Workflow", WORKFLOW_INTERFACE_AVAILABLE_NODES + WORKFLOW_AVAILABLE_NODES),
-        AdapterGroup("Sinks", SINKS_AVAILABLE_NODES),
+        AdapterGroup("Sinks", SINKS_AVAILABLE_NODES + (PARAVIEW_BRIDGE,)),
         AdapterGroup("Doc", DOCUMENTATION_AVAILABLE_NODES),
         AdapterGroup(
             "External Tools",

flowgraph-0.1.7/src/flowgraph/adapters/calculator.py

@@ -0,0 +1,120 @@
+"""Trusted Python-expression calculator with positional and upstream-name inputs."""
+
+import builtins
+import keyword
+import re
+from collections import Counter
+from collections.abc import Mapping
+from typing import Any
+
+import numpy as np
+
+from flowgraph.application.workflow_core import (
+    ExecContext,
+    NodeDefinition,
+    NodeInstance,
+    NodeRegistry,
+    ParameterDefinition,
+    PortDefinition,
+    PortDirection,
+    WorkflowEdge,
+)
+
+from .data_types import ANY, ParameterKind
+
+
+def _numeric_value(value: Any, label: str) -> Any:
+    """Normalize lists and expose numeric array storage through a read-only view."""
+    if isinstance(value, list):
+        value = np.asarray(value)
+    if isinstance(value, np.ndarray):
+        if value.dtype.kind not in "buifc":
+            raise TypeError(f"Calculator {label} must contain numeric values")
+        view = value.view(np.ndarray)
+        view.flags.writeable = False
+        return view
+    if isinstance(value, (bool, int, float, complex, np.number, np.bool_)):
+        if np.asarray(value).dtype.kind not in "buifc":
+            raise TypeError(f"Calculator {label} must be numeric")
+        return value.item() if isinstance(value, np.generic) else value
+    raise TypeError(f"Calculator {label} must be a numeric scalar or NumPy array")
+
+
+def _calculate(
+    inputs: Mapping[str, Any],
+    parameters: Mapping[str, Any],
+    input_edges: Mapping[str, WorkflowEdge],
+) -> Mapping[str, Any]:
+    """Evaluate one trusted expression; this is intentionally not a sandbox."""
+    formula = inputs.get("formula", parameters.get("formula", "0"))
+    if not isinstance(formula, str) or not formula.strip():
+        raise ValueError("Calculator formula must be a non-empty Python expression")
+
+    namespace = {
+        name: _numeric_value(inputs[name], f"input {name!r}")
+        for index in range(1, 126)
+        if (name := f"input_{index}") in inputs
+    }
+    data_names = frozenset(namespace)
+    names = Counter(edge.source_port for name, edge in input_edges.items() if name in data_names)
+    for name, edge in input_edges.items():
+        alias = edge.source_port
+        if (
+            name in data_names
+            and names[alias] == 1
+            and alias.isidentifier()
+            and not keyword.iskeyword(alias)
+            and not re.fullmatch(r"input_[0-9]+", alias)
+            and alias not in {"np", "__builtins__"}
+            and not hasattr(builtins, alias)
+        ):
+            namespace[alias] = namespace[name]
+    namespace.update(np=np, __builtins__=builtins.__dict__)
+    try:
+        # One shared namespace also makes aliases available inside comprehensions/lambdas.
+        result = eval(compile(formula.strip(), "<calculator formula>", "eval"), namespace)
+    except Exception as error:
+        raise ValueError(f"Calculator formula failed ({type(error).__name__}): {error}") from error
+    if isinstance(result, list):
+        raise TypeError("Calculator result must be a numeric scalar or NumPy array; use np.array")
+    return {"result": _numeric_value(result, "result")}
+
+
+def _calculator(
+    inputs: Mapping[str, Any],
+    parameters: Mapping[str, Any],
+    _exec_context: ExecContext | None = None,
+) -> Mapping[str, Any]:
+    """Evaluate using numbered names when called without workflow provenance."""
+    return _calculate(inputs, parameters, {})
+
+
+def _calculator_instance(
+    _instance: NodeInstance,
+    inputs: Mapping[str, Any],
+    parameters: Mapping[str, Any],
+    _registry: NodeRegistry,
+    input_edges: Mapping[str, WorkflowEdge],
+    _exec_context: ExecContext,
+) -> Mapping[str, Any]:
+    """Resolve optional aliases from actual upstream output port names."""
+    return _calculate(inputs, parameters, input_edges)
+
+
+CALCULATOR = NodeDefinition(
+    id="calculator",
+    label="Calculator",
+    icon="mdi-calculator",
+    description="Evaluate a trusted Python expression with np, numbered inputs and unique aliases.",
+    requirements=("py:numpy",),
+    ports=(
+        PortDefinition("input", PortDirection.INPUT, ANY, "Input", required=False, expandable=125),
+        PortDefinition("result", PortDirection.OUTPUT, ANY, "Result"),
+    ),
+    parameters=(ParameterDefinition("formula", ParameterKind.TEXT, "Formula", "0", "input_1 * 2"),),
+    executor=_calculator,
+    edge_aware_instance_executor=_calculator_instance,
+    cache_policy="always",
+)
+
+__all__ = ["CALCULATOR"]

{flowgraph-0.1.6 → flowgraph-0.1.7}/src/flowgraph/adapters/controls.py

@@ -35,17 +35,15 @@ def _slider_bounds(
         value_type = "integer" if integer else "number"
         raise TypeError(f"The slider min, max, and value must be {value_type}s")
 
-    if integer:
-        if minimum >= maximum:
-            raise ValueError("The slider minimum must be less than its maximum")
-    else:
+    if not integer:
         minimum = float(minimum)
         maximum = float(maximum)
         value = float(value)
         if not all(math.isfinite(item) for item in (minimum, maximum, value)):
             raise ValueError("The slider min, max, and value must be finite")
-        if minimum >= maximum:
-            raise ValueError("The slider minimum must be less than its maximum")
+
+    if minimum > maximum:
+        raise ValueError("The slider minimum must be less than or equal to its maximum")
 
     if not minimum <= value <= maximum:
         raise ValueError("The slider value must be between its minimum and maximum")
@@ -73,7 +71,7 @@ FLOAT_SLIDER = NodeDefinition(
     parameters=(
         ParameterDefinition("min", ParameterKind.FLOAT, "Minimum", 0.0, "0.0"),
         ParameterDefinition("max", ParameterKind.FLOAT, "Maximum", 1.0, "1.0"),
-        ParameterDefinition("value", ParameterKind.FLOAT, "Value", 0.5, "0.5", port=False),
+        ParameterDefinition("value", ParameterKind.FLOAT, "Value", 0.5, "0.5"),
     ),
 )
 
@@ -99,7 +97,7 @@ INT_SLIDER = NodeDefinition(
     parameters=(
         ParameterDefinition("min", ParameterKind.INTEGER, "Minimum", 0, "0"),
         ParameterDefinition("max", ParameterKind.INTEGER, "Maximum", 100, "100"),
-        ParameterDefinition("value", ParameterKind.INTEGER, "Value", 50, "50", port=False),
+        ParameterDefinition("value", ParameterKind.INTEGER, "Value", 50, "50"),
     ),
 )
 

{flowgraph-0.1.6 → flowgraph-0.1.7}/src/flowgraph/adapters/cosapp.py

@@ -169,7 +169,7 @@ COSAPP_WORKFLOW = NodeDefinition(
             "",
             "Path to a trusted Python file defining the CoSApp model",
             file_patterns=("*.py",),
-            port=False,
+            port=True,
         ),
         ParameterDefinition(
             "factory",

{flowgraph-0.1.6 → flowgraph-0.1.7}/src/flowgraph/adapters/data_types.py

@@ -1,8 +1,9 @@
 from pathlib import Path
 
 import numpy as np
+from Muscat.ImplicitGeometry.ImplicitGeometryBase import ImplicitGeometryBase
 from Muscat.LinAlg.Transform import Transform
-from Muscat.MeshContainers.Filters.FilterObjects import ElementFilter
+from Muscat.MeshContainers.Filters.FilterObjects import ElementFilter, NodeFilter
 from Muscat.MeshContainers.Filters.FilterOperators import FilterOperatorBase
 from PIL.Image import Image
 
@@ -11,6 +12,9 @@ from flowgraph.domain.filepath import FilePath
 from flowgraph.domain.mesh_document import MeshDocument
 
 ANY = DataType("any", "Any", object)
+ARRAY = DataType("array", "Array", np.ndarray)
+ARRAY_1D = DataType("array-1d", "1D Array", np.ndarray)
+ARRAY_2D = DataType("array-2d", "2D Array", np.ndarray)
 STRING = DataType("string", "Text", str)
 STR_SELECT = DataType("str", "select str", str)
 BOOLEAN = DataType("boolean", "Boolean", bool)
@@ -18,6 +22,8 @@ INTEGER = DataType("integer", "Integer", int)
 FLOAT = DataType("float", "Float", float)
 LIST_STR = DataType("list[str]", "List Text", list[str])
 LIST_INT = DataType("list[int]", "List Ints", list[int])
+# JSON-friendly parameter editors and APIs explicitly requiring Python lists.
+# Numeric data ports should normally use ARRAY_1D instead.
 LIST_FLOAT = DataType("list[float]", "List Floats", list[float])
 LIST_ANY = DataType("list[any]", "List Any", list)
 FILE = DataType("filename", "FilePath", FilePath)
@@ -28,11 +34,16 @@ MESH_DOCUMENT = DataType("mesh-document", "Mesh document", MeshDocument)
 TABLE_DOCUMENT = DataType("table-document", "Table", dict)
 IMAGE = DataType("image", "Image", Image)
 IMAGEJ = DataType("imagej", "ImageJ NumPy", np.ndarray)
+MUSCAT_ZONE = DataType("muscat-zone", "Zone", ImplicitGeometryBase)
 MUSCAT_ELEMENT_FILTER = DataType(
     "filter-like",
     "Selector",
     (ElementFilter, FilterOperatorBase),
 )
+# Element filters also implement GetNodesIndices and can serve as nodal filters.
+MUSCAT_NODE_FILTER = DataType(
+    "node-filter-like", "Node Selector", (NodeFilter, ElementFilter, FilterOperatorBase)
+)
 VEC3D = DataType("VEC3D", "3D Vector", list[float])
 VEC2D = DataType("VEC2D", "2D Vector", list[float])
 VEC3DSTR = DataType("VEC3DSTR", "3D Text Vector", list[str])

flowgraph-0.1.7/src/flowgraph/adapters/field_gradient.py

@@ -0,0 +1,136 @@
+"""Scalar/vector nodal derivatives using Muscat's FE/IP field representations."""
+
+import numpy as np
+from Muscat.FE.Fields.FieldTools import NodeFieldToFEField, TransferFEFieldToIPField
+from Muscat.MeshContainers import ElementsDescription as ED
+from Muscat.MeshContainers.Filters.FilterObjects import ElementFilter
+
+from flowgraph.adapters.data_types import (
+    ARRAY_2D,
+    MESH_DOCUMENT,
+    MUSCAT_ELEMENT_FILTER,
+    ParameterKind,
+)
+from flowgraph.adapters.mesh_analysis import _editable_elements
+from flowgraph.adapters.mesh_composition import _field_name, _fields, _publish
+from flowgraph.application.workflow_core import (
+    NodeDefinition,
+    ParameterDefinition,
+    ParameterOption,
+    PortDefinition,
+    PortDirection,
+)
+
+
+def _gradient(inputs, parameters, _exec_context=None, *, vector=False):
+    """Differentiate a scalar/vector node field on selected elements using Muscat."""
+    source = inputs["mesh"].mesh
+    name = _field_name(parameters.get("fieldName", ""))
+    if name not in source.nodeFields:
+        raise ValueError(f"{'Vector' if vector else 'Scalar'} node field {name!r} does not exist")
+    scalar = source.nodeFields[name]
+    shape_valid = (
+        scalar.ndim == 2
+        and scalar.shape[0] == source.GetNumberOfNodes()
+        and scalar.shape[1] in (2, 3)
+        if vector
+        else scalar.shape in ((source.GetNumberOfNodes(),), (source.GetNumberOfNodes(), 1))
+    )
+    if not shape_valid or scalar.dtype.kind not in "iuf" or not np.isfinite(scalar).all():
+        kind = (
+            "vector node field of shape (N, 2) or (N, 3)"
+            if vector
+            else "scalar node field of shape (N,) or (N, 1)"
+        )
+        raise ValueError(f"Source must be a finite real {kind}")
+    entity = parameters.get("entity", "node")
+    destination = _fields(source, entity)
+    target = _field_name(parameters.get("targetName", "") or f"{name}_gradient")
+    if target in destination and not parameters.get("overwrite", False):
+        raise ValueError(f"Destination field {target!r} already exists")
+
+    # Muscat FE routines cache numbering/offset metadata. Detach containers, not
+    # geometry/fields, so backend bookkeeping cannot change the upstream mesh.
+    mesh = _editable_elements(source)
+    selector = inputs.get("filter")
+    if selector is None:
+        selector = ElementFilter(dimensionality=mesh.GetElementsDimensionality())
+    dimensions = {ED.dimensionality[s.elementType] for s in selector(mesh) if s.Size()}
+    if len(dimensions) > 1 or 0 in dimensions:
+        raise ValueError("Gradient requires a single element dimension of 1, 2, or 3")
+    count = mesh.GetNumberOfNodes() if entity == "node" else mesh.GetNumberOfElements()
+    dimension = mesh.GetPointsDimensionality()
+    components = scalar.shape[1] if vector else 1
+    values = np.zeros((count, components * dimension))
+    if dimensions:
+        fields = NodeFieldToFEField(mesh, {"source": scalar if vector else scalar.reshape(-1)})
+        for component in range(components):
+            field = fields[f"source_{component}" if vector else "source"]
+            for axis in range(dimension):
+                derivative = TransferFEFieldToIPField(field, der=axis, elementFilter=selector)
+                column = component * dimension + axis
+                if entity == "element":
+                    values[:, column] = derivative.GetCellRepresentation()
+                else:
+                    values[:, column] = (
+                        derivative.GetIpFieldRepresentation().GetPointRepresentation(
+                            elementFilter=selector
+                        )
+                    )
+    _fields(mesh, entity)[target] = values
+    document = _publish(mesh)
+    return {"mesh": document, "gradient": _fields(document.mesh, entity)[target]}
+
+
+def _vector_gradient(inputs, parameters, _exec_context=None):
+    """Compute component-major vector derivatives using Muscat, at nodes or cells."""
+    return _gradient(inputs, parameters, _exec_context, vector=True)
+
+
+SCALAR_FIELD_GRADIENT = NodeDefinition(
+    id="scalar-field-gradient",
+    label="Scalar Field Gradient",
+    icon="mdi-vector-line",
+    description="Compute a scalar node field gradient on selected elements, at nodes or cells.",
+    requirements=("py:muscat", "py:numpy"),
+    ports=(
+        PortDefinition("mesh", PortDirection.INPUT, MESH_DOCUMENT, "Mesh"),
+        PortDefinition(
+            "filter", PortDirection.INPUT, MUSCAT_ELEMENT_FILTER, "Element selector", required=False
+        ),
+        PortDefinition("mesh", PortDirection.OUTPUT, MESH_DOCUMENT, "Mesh"),
+        PortDefinition("gradient", PortDirection.OUTPUT, ARRAY_2D, "Gradient"),
+    ),
+    parameters=(
+        ParameterDefinition("fieldName", ParameterKind.TEXT, "Scalar node field", ""),
+        ParameterDefinition(
+            "entity",
+            ParameterKind.STR_SELECT,
+            "Output association",
+            "node",
+            options=(
+                ParameterOption("node", "Nodes"),
+                ParameterOption("element", "Cells / Elements"),
+            ),
+        ),
+        ParameterDefinition(
+            "targetName", ParameterKind.TEXT, "Output field (empty: source_gradient)", ""
+        ),
+        ParameterDefinition("overwrite", ParameterKind.BOOLEAN, "Overwrite target", False),
+    ),
+    executor=_gradient,
+)
+
+VECTOR_FIELD_GRADIENT = NodeDefinition(
+    id="vector-field-gradient",
+    label="Vector Field Gradient",
+    icon="mdi-matrix",
+    description="Compute a nodal vector gradient tensor on selected elements, at nodes or cells.",
+    requirements=SCALAR_FIELD_GRADIENT.requirements,
+    ports=tuple(port for port in SCALAR_FIELD_GRADIENT.ports if not port.is_param),
+    parameters=(
+        ParameterDefinition("fieldName", ParameterKind.TEXT, "Vector node field", ""),
+        *SCALAR_FIELD_GRADIENT.parameters[1:],
+    ),
+    executor=_vector_gradient,
+)