User expression support [POC] (#789)

.github/workflows/codestyle.yml

@@ -1,11 +1,3 @@
-# This workflow will upload a Python Package using Twine when a release is created
-# For more information see: https://help.github.com/en/actions/language-and-framework-guides/using-python-with-github-actions#publishing-to-package-registries
-
-# This workflow uses actions that are not certified by GitHub.
-# They are provided by a third-party and are governed by
-# separate terms of service, privacy policy, and support
-# documentation.
-
 name: Codestyle checking
 
 on:

.github/workflows/test.yml

@@ -6,7 +6,6 @@ on:
     branches: [ develop, release-candidate/* ]
   pull_request:
     types: [ opened, synchronize, reopened, ready_for_review ]
-    branches: [ develop, release-candidate/* ]
   workflow_call:
 
 jobs:

flow360/__init__.py

@@ -145,6 +145,9 @@
     SI_unit_system,
     imperial_unit_system,
 )
+from flow360.component.simulation.user_code.core.types import UserVariable
+from flow360.component.simulation.user_code.functions import math
+from flow360.component.simulation.user_code.variables import control, solution
 from flow360.component.simulation.user_defined_dynamics.user_defined_dynamics import (
     UserDefinedDynamic,
 )
@@ -274,5 +277,9 @@
     "StreamlineOutput",
     "Transformation",
     "WallRotation",
+    "UserVariable",
+    "math",
+    "control",
+    "solution",
     "report",
 ]

flow360/component/project_utils.py

@@ -21,6 +21,7 @@
 from flow360.component.simulation.primitives import Box, Cylinder, GhostSurface
 from flow360.component.simulation.simulation_params import SimulationParams
 from flow360.component.simulation.unit_system import LengthType
+from flow360.component.simulation.user_code.core.types import save_user_variables
 from flow360.component.simulation.utils import model_attribute_unlock
 from flow360.component.simulation.web.asset_base import AssetBase
 from flow360.component.utils import parse_datetime
@@ -281,6 +282,9 @@ def set_up_params_for_uploading(
 
     params = _set_up_default_reference_geometry(params, length_unit)
 
+    # Convert all reference of UserVariables to VariableToken
+    params = save_user_variables(params)
+
     return params
 
 

flow360/component/simulation/blueprint/__init__.py

@@ -0,0 +1,18 @@
+"""Blueprint: Safe function serialization and visual programming integration."""
+
+from flow360.component.simulation.blueprint.core.generator import model_to_function
+from flow360.component.simulation.blueprint.core.parser import (
+    expr_to_model,
+    function_to_model,
+)
+
+from .core.function import FunctionNode
+from .core.types import Evaluable
+
+__all__ = [
+    "FunctionNode",
+    "Evaluable",
+    "function_to_model",
+    "model_to_function",
+    "expr_to_model",
+]

flow360/component/simulation/blueprint/core/__init__.py

@@ -0,0 +1,111 @@
+"""Core blueprint functionality."""
+
+from .context import EvaluationContext, ReturnValue
+from .expressions import (
+    BinOpNode,
+    CallModelNode,
+    ConstantNode,
+    ExpressionNode,
+    ExpressionNodeType,
+    ListCompNode,
+    ListNode,
+    NameNode,
+    RangeCallNode,
+    SubscriptNode,
+    TupleNode,
+)
+from .function import FunctionNode
+from .generator import expr_to_code, model_to_function, stmt_to_code
+from .parser import function_to_model
+from .statements import (
+    AssignNode,
+    AugAssignNode,
+    ForLoopNode,
+    IfElseNode,
+    ReturnNode,
+    StatementNode,
+    StatementNodeType,
+    TupleUnpackNode,
+)
+from .types import Evaluable, TargetSyntax
+
+
+def _model_rebuild() -> None:
+    """Update forward references in the correct order."""
+    namespace = {
+        # Expression types
+        "NameNode": NameNode,
+        "ConstantNode": ConstantNode,
+        "BinOpNode": BinOpNode,
+        "RangeCallNode": RangeCallNode,
+        "CallModelNode": CallModelNode,
+        "TupleNode": TupleNode,
+        "ListNode": ListNode,
+        "ListCompNode": ListCompNode,
+        "SubscriptNode": SubscriptNode,
+        "ExpressionNodeType": ExpressionNodeType,
+        # Statement types
+        "AssignNode": AssignNode,
+        "AugAssignNode": AugAssignNode,
+        "IfElseNode": IfElseNode,
+        "ForLoopNode": ForLoopNode,
+        "ReturnNode": ReturnNode,
+        "TupleUnpackNode": TupleUnpackNode,
+        "StatementNodeType": StatementNodeType,
+        # Function type
+        "FunctionNode": FunctionNode,
+    }
+
+    # First update expression classes that only depend on ExpressionType
+    BinOpNode.model_rebuild(_types_namespace=namespace)
+    RangeCallNode.model_rebuild(_types_namespace=namespace)
+    CallModelNode.model_rebuild(_types_namespace=namespace)
+    TupleNode.model_rebuild(_types_namespace=namespace)
+    ListNode.model_rebuild(_types_namespace=namespace)
+    ListCompNode.model_rebuild(_types_namespace=namespace)
+    SubscriptNode.model_rebuild(_types_namespace=namespace)
+
+    # Then update statement classes that depend on both types
+    AssignNode.model_rebuild(_types_namespace=namespace)
+    AugAssignNode.model_rebuild(_types_namespace=namespace)
+    IfElseNode.model_rebuild(_types_namespace=namespace)
+    ForLoopNode.model_rebuild(_types_namespace=namespace)
+    ReturnNode.model_rebuild(_types_namespace=namespace)
+    TupleUnpackNode.model_rebuild(_types_namespace=namespace)
+
+    # Finally update Function class
+    FunctionNode.model_rebuild(_types_namespace=namespace)
+
+
+# Update forward references
+_model_rebuild()
+
+
+__all__ = [
+    "ExpressionNode",
+    "NameNode",
+    "ConstantNode",
+    "BinOpNode",
+    "RangeCallNode",
+    "CallModelNode",
+    "TupleNode",
+    "ListNode",
+    "ListCompNode",
+    "ExpressionNodeType",
+    "StatementNode",
+    "AssignNode",
+    "AugAssignNode",
+    "IfElseNode",
+    "ForLoopNode",
+    "ReturnNode",
+    "TupleUnpackNode",
+    "StatementNodeType",
+    "FunctionNode",
+    "EvaluationContext",
+    "ReturnValue",
+    "Evaluable",
+    "expr_to_code",
+    "stmt_to_code",
+    "model_to_function",
+    "function_to_model",
+]

flow360/component/simulation/blueprint/core/context.py

@@ -0,0 +1,154 @@
+"""Evaluation context that contains references to known symbols"""
+
+from typing import Any, Optional
+
+import pydantic as pd
+
+from flow360.component.simulation.blueprint.core.resolver import CallableResolver
+
+
+class ReturnValue(Exception):
+    """
+    Custom exception to signal a 'return' during the evaluation
+    of a function model.
+    """
+
+    def __init__(self, value: Any):
+        super().__init__("Function returned.")
+        self.value = value
+
+
+class EvaluationContext:
+    """
+    Manages variable scope and access during function evaluation.
+
+    This class stores named values and optionally resolves names through a
+    `CallableResolver` when not already defined in the context.
+    """
+
+    def __init__(
+        self, resolver: CallableResolver, initial_values: Optional[dict[str, Any]] = None
+    ) -> None:
+        """
+        Initialize the evaluation context.
+
+        Args:
+            resolver (CallableResolver): A resolver used to look up callable names
+                and constants if not explicitly defined.
+            initial_values (Optional[dict[str, Any]]): Initial variable values to populate
+                the context with.
+        """
+        self._values = initial_values or {}
+        self._data_models = {}
+        self._resolver = resolver
+        self._aliases: dict[str, str] = {}
+
+    def get(self, name: str, resolve: bool = True) -> Any:
+        """
+        Retrieve a value by name from the context.
+
+        If the name is not explicitly defined and `resolve` is True,
+        attempt to resolve it using the resolver.
+
+        Args:
+            name (str): The variable or callable name to retrieve.
+            resolve (bool): Whether to attempt to resolve the name if it's undefined.
+
+        Returns:
+            Any: The corresponding value.
+
+        Raises:
+            NameError: If the name is not found and cannot be resolved.
+            ValueError: If resolution is disabled and the name is undefined.
+        """
+        if name not in self._values:
+            # Try loading from builtin callables/constants if possible
+            try:
+                if not resolve:
+                    raise ValueError(f"{name} was not defined explicitly in the context")
+                val = self.resolve(name)
+                # If successful, store it so we don't need to import again
+                self._values[name] = val
+            except ValueError as err:
+                raise NameError(f"Name '{name}' is not defined") from err
+        return self._values[name]
+
+    def get_data_model(self, name: str) -> Optional[pd.BaseModel]:
+        """Get the Validation model for the given name."""
+        if name not in self._data_models:
+            return None
+        return self._data_models[name]
+
+    def set_alias(self, name, alias) -> None:
+        """
+        Set alias used for code generation.
+        This is meant for non-user variables.
+        """
+        self._aliases[name] = alias
+
+    def get_alias(self, name) -> Optional[str]:
+        """
+        Get alias used for code generation.
+        This is meant for non-user variables.
+        """
+        return self._aliases.get(name)
+
+    def set(self, name: str, value: Any, data_model: pd.BaseModel = None) -> None:
+        """
+        Assign a value to a name in the context.
+
+        Args:
+            name (str): The variable name to set.
+            value (Any): The value to assign.
+            data_model (BaseModel, optional): The type of the associate with this entry (for non-user variables)
+        """
+        self._values[name] = value
+
+        if data_model:
+            self._data_models[name] = data_model
+
+    def resolve(self, name):
+        """
+        Resolve a name using the provided resolver.
+
+        Args:
+            name (str): The name to resolve.
+
+        Returns:
+            Any: The resolved callable or constant.
+
+        Raises:
+            ValueError: If the name cannot be resolved by the resolver.
+        """
+        return self._resolver.get_allowed_callable(name)
+
+    def can_evaluate(self, name) -> bool:
+        """
+        Check if the name can be evaluated via the resolver.
+
+        Args:
+            name (str): The name to check.
+
+        Returns:
+            bool: True if the name is allowed and resolvable, False otherwise.
+        """
+        return self._resolver.can_evaluate(name)
+
+    def copy(self) -> "EvaluationContext":
+        """
+        Create a copy of the current context.
+
+        Returns:
+            EvaluationContext: A new context instance with the same resolver and a copy
+            of the current variable values.
+        """
+        return EvaluationContext(self._resolver, dict(self._values))
+
+    @property
+    def user_variable_names(self):
+        """Get the set of user variables in the context."""
+        return {name for name in self._values.keys() if "." not in name}
+
+    def clear(self):
+        """Clear user variables from the context."""
+        self._values = {name: value for name, value in self._values.items() if "." in name}