fluxrender 0.1.4__tar.gz → 0.2.0__tar.gz

{fluxrender-0.1.4 → fluxrender-0.2.0}/FluxRender/__init__.py

@@ -1,10 +1,10 @@
 from .core import Scene, CoordinateSystem
-from .ui import Button, UIStyle, Grid, Axis, VBox, HBox, create_mode_switch, create_property_switch, create_color_scale_switch
+from .ui import Button, UIStyle, Grid, Axis, VBox, HBox, create_mode_switch, create_property_switch, create_color_scale_switch, DynamicText, create_cursor_probe_display
 from .entities import VectorField, ParticleSystem
 from .regions import CircularRegion, CursorRegion
 from .math_engine import VectorMathEngine
 from .probes import DataProbe
-from .shortcuts import create_workspace, quick_simulate
+from .shortcuts import create_workspace, quick_simulate, as_vector_field
 
 
 from .constants import Align, Property, ArrowStyle, FieldMode, ScaleType

{fluxrender-0.1.4 → fluxrender-0.2.0}/FluxRender/core.py

@@ -7,7 +7,7 @@ import os
 import atexit
 
 from .colors import ColorSequence
-from .validators import _fatal_error, PositiveInt, StrictBool, StrictString, NumberRange
+from .validators import _fatal_error, PositiveInt, StrictBool, StrictString, NumberRange, _count_function_parameters
 
 # region initial settings [blue]
 
@@ -120,6 +120,7 @@ class CoordinateSystem:
     remain circular).
 
     Attributes:
+        resolution (tuple): The screen resolution as (width, height) in pixels.
         width (int): Screen width in pixels.
         height (int): Screen height in pixels.
         x_min (float): The actual lower bound of the mathematical X axis.
@@ -135,7 +136,7 @@ class CoordinateSystem:
     keep_aspect_ratio = StrictBool()
 
 
-    def __init__(self, x_range: tuple, y_range: tuple, width: int, height: int, keep_aspect_ratio: bool = False):
+    def __init__(self, x_range: tuple = (-8, 8), y_range: tuple = (-8, 8), resolution: tuple = (1200, 800), keep_aspect_ratio: bool = False):
         """
         Initializes the coordinate system with specific bounds and screen dimensions.
 
@@ -147,8 +148,7 @@ class CoordinateSystem:
         Args:
             x_range (tuple[float, float]): The desired (min, max) values for the X axis.
             y_range (tuple[float, float]): The desired (min, max) values for the Y axis.
-            width (int): Window/buffer width in pixels.
-            height (int): Window/buffer height in pixels.
+            resolution (tuple[int, int], optional): The screen resolution as (width, height) in pixels. Defaults to (1200, 800).
             keep_aspect_ratio (bool, optional): If True, adjusts x_range or y_range
                 to preserve 1:1 scaling (square pixels). Defaults to False.
 
@@ -156,18 +156,19 @@ class CoordinateSystem:
         Example:
             To create a coordinate system that maps the mathematical range of -2 to 2 on both axes to a screen resolution of 1800x950 pixels without keeping the aspect ratio:
             ```python
-            coords = CoordinateSystem((-2, 2), (-2, 2), 1800, 950, keep_aspect_ratio=False)
+            coords = CoordinateSystem((-2, 2), (-2, 2), (1800, 950), keep_aspect_ratio=False)
             ```
 
             To create the same coordinate system but with aspect ratio correction (ensuring circles look like circles):
             ```python
-            coords = CoordinateSystem((-2, 2), (-2, 2), 1800, 950, keep_aspect_ratio=True)
+            coords = CoordinateSystem((-2, 2), (-2, 2), (1800, 950), keep_aspect_ratio=True)
             ```
             Then, in the above case, the ranges on the X and Y axis will be adjusted accordingly to maintain the aspect ratio.
         """
 
-        self.width = width
-        self.height = height
+        self.resolution = resolution
+        self.width = resolution[0]
+        self.height = resolution[1]
 
         self.math_width = x_range[1] - x_range[0]
         self.math_height = y_range[1] - y_range[0]
@@ -175,7 +176,7 @@ class CoordinateSystem:
         y_center = (y_range[0] + y_range[1]) / 2.0
 
         if keep_aspect_ratio:
-            screen_ratio = width / height
+            screen_ratio = self.width / self.height
             data_ratio = self.math_width / self.math_height
 
             if screen_ratio < data_ratio:
@@ -416,7 +417,7 @@ class Scene:
             ```python
             import FluxRender as fr
 
-            coords = fr.CoordinateSystem((-10, 10), (-10, 10), 1200, 800, keep_aspect_ratio=True)
+            coords = fr.CoordinateSystem(x_range=(-10, 10), y_range=(-10, 10), resolution=(1200, 800), keep_aspect_ratio=True)
 
             scene = fr.Scene(
                 "My Simulation",
@@ -445,6 +446,7 @@ class Scene:
         self.scene_layer = ti.Vector.field(4, dtype=float, shape=(self.width, self.height))
         self.ui_layer = ti.Vector.field(4, dtype=float, shape=(self.width, self.height))
         self.ui_layer.fill(0)
+        self.dynamic_ui_layer = ti.Vector.field(4, dtype=float, shape=(self.width, self.height))
         self.pixels = ti.Vector.field(3, dtype=float, shape=(self.width, self.height))
 
         self.zoom_speed = 0.02
@@ -452,6 +454,7 @@ class Scene:
         self._use_trails = False
 
         self.objects = []
+        self.functions = []
 
         self.time = 0.0
         self.dt = 0.005
@@ -498,6 +501,7 @@ class Scene:
             self._fade_trails(self.trail_fade_factor)
 
             self.scene_layer.fill(0) # Completely clear scene_layer
+            self.dynamic_ui_layer.fill(0) # Clear dynamic UI layer
 
             # Handling user interactions (e.g., mouse clicks)
             mx, my = window.get_cursor_pos()
@@ -530,6 +534,9 @@ class Scene:
                 obj.render(self)
                 obj.update(self)
 
+            # Execute all registered callable functions
+            for func in self.functions:
+                func()
 
             # User update() function executed every frame
             if user_update_func:
@@ -555,6 +562,7 @@ class Scene:
             trail = self.trail_layer[i, j]
             overlay = self.scene_layer[i, j]
             ui = self.ui_layer[i, j]
+            dynamic_ui = self.dynamic_ui_layer[i, j]
 
             # background + trail_layer
             color_step1 = trail.xyz * trail.w + self._background_color_ti * (1.0 - trail.w)
@@ -563,7 +571,10 @@ class Scene:
             color_step2 = overlay.xyz * overlay.w + color_step1 * (1.0 - overlay.w)
 
             # color_step2 + ui_layer
-            final_rgb = ui.xyz * ui.w + color_step2 * (1.0 - ui.w)
+            color_step3 = ui.xyz * ui.w + color_step2 * (1.0 - ui.w)
+
+            # color_step3 + dynamic_ui_layer
+            final_rgb = dynamic_ui.xyz * dynamic_ui.w + color_step3 * (1.0 - dynamic_ui.w)
 
             self.pixels[i, j] = final_rgb
 
@@ -601,7 +612,27 @@ class Scene:
             self.objects.append(new_object)
             self._process_addition(new_object)
             if hasattr(new_object, '_init'):
-                new_object._init(self)
+                num_of_parameters = _count_function_parameters(new_object._init)
+                if num_of_parameters == 1:
+                    new_object._init(self)
+                elif num_of_parameters == 0:
+                    new_object._init()
+
+    def add_callable(self, func):
+        """
+        Adds a callable function to be executed every frame.
+
+        The function must be a callable object (e.g., a function or a lambda).
+        It will be called on every frame update, just before the rendering phase.
+
+        Args:
+            func (Callable): A callable object to be executed every frame. It can be used for custom animations, state updates, or any logic that needs to run continuously.
+        """
+
+        if not callable(func):
+            _fatal_error("The provided object must be callable (e.g., a function or a lambda).", "TypeError")
+
+        self.functions.append(func)
 
     def _process_addition(self, entity):
         """

{fluxrender-0.1.4 → fluxrender-0.2.0}/FluxRender/entities.py

@@ -21,7 +21,7 @@ class Renderable:
     def update(self, scene: cr.Scene):
         pass
 
-    def _init(self, scene: cr.Scene):
+    def _init(self, scene: cr.Scene = None):
         pass
 
 class VectorEntity(Renderable):
@@ -272,6 +272,38 @@ class VectorEntity(Renderable):
 
         return self.math_engine._safe_evaluate_scalar_function(user_defined_function, *spatial_arguments)
 
+    def evaluate_field_and_property(self, property_type: Property | None, spatial_coordinate_x: float, spatial_coordinate_y: float):
+        """
+        Evaluates the primary vector function and the specified property at the given spatial coordinates.
+
+        This method behaves exactly like evaluate_vector_field, but additionally calculates
+        a scalar value given by property_type (e.g. divergence, rotation, velocity).
+
+        Args:
+            property_type (Property | None): The specific property to calculate based on the evaluated vector field. If set to None, the method will only evaluate the primary vector function and bypass any property calculations for maximum performance when only vector components are needed.
+            spatial_coordinate_x (float / ndarray): The x-coordinate(s) in the mathematical world space.
+            spatial_coordinate_y (float / ndarray): The y-coordinate(s) in the mathematical world space.
+
+        Returns:
+            tuple: A tuple (vector_x, vector_y, property_value) where:
+                - vector_x (float / ndarray): The x-component(s) of the evaluated vector field.
+                - vector_y (float / ndarray): The y-component(s) of the evaluated vector field.
+                - property_value (float / ndarray or None): The calculated property value based on the specified property_type. This will be None if property_type is set to None, indicating that no property calculation was performed.
+
+        Notes:
+            * **Performance Optimization** This method is optimized for performance. If the caller only requires the vector components without any derived properties, they can set property_type to None to skip the property evaluation step entirely, which can significantly reduce computation time, especially for complex properties that require additional function evaluations.
+            * **Time Injection** If the primary vector function or the property evaluator function is time-dependent, this method will automatically inject the current simulation time during their evaluation, allowing for dynamic, time-evolving fields without requiring the user to manage time parameters manually.
+
+        Example:
+            Evaluating the vector field and its velocity property at a single point:
+            ```python
+
+            ```
+
+        """
+
+        return self.math_engine.evaluate_field_and_property(property_type, spatial_coordinate_x, spatial_coordinate_y)
+
 
 
 @ti.dataclass

{fluxrender-0.1.4 → fluxrender-0.2.0}/FluxRender/math_engine.py

@@ -376,7 +376,7 @@ class VectorMathEngine(MathEngine):
                 spatial_coordinate_y,
             )
 
-    def evaluate_field_and_property(self, property_type: Property, spatial_coordinate_x: float, spatial_coordinate_y: float) -> tuple:
+    def evaluate_field_and_property(self, property_type: Property | None, spatial_coordinate_x: float, spatial_coordinate_y: float) -> tuple:
         """
         Evaluates the primary vector function and the specified property at the given spatial coordinates.
 
@@ -384,7 +384,7 @@ class VectorMathEngine(MathEngine):
         a scalar value given by property_type (e.g. divergence, rotation, velocity).
 
         Args:
-            property_type (Property): The specific property to calculate based on the evaluated vector field. If set to None, the method will only evaluate the primary vector function and bypass any property calculations for maximum performance when only vector components are needed.
+            property_type (Property | None): The specific property to calculate based on the evaluated vector field. If set to None, the method will only evaluate the primary vector function and bypass any property calculations for maximum performance when only vector components are needed.
             spatial_coordinate_x (float / ndarray): The x-coordinate(s) in the mathematical world space.
             spatial_coordinate_y (float / ndarray): The y-coordinate(s) in the mathematical world space.
 
@@ -498,7 +498,12 @@ class VectorMathEngine(MathEngine):
             magnitudes = np.hypot(vec_dx, vec_dy) * np.hypot(base_vec_dx, base_vec_dy)
 
 
-        magnitudes[magnitudes == 0] = 1.0
+        if isinstance(magnitudes, np.ndarray):
+            magnitudes[magnitudes == 0] = 1.0
+        else:
+            if magnitudes == 0:
+                magnitudes = 1.0
+
         angles = np.arccos(np.clip(dot_products / magnitudes, -1.0, 1.0)) # Angle in radians between the vector and the base angle vector
 
         return angles

{fluxrender-0.1.4 → fluxrender-0.2.0}/FluxRender/probes.py

@@ -1,8 +1,8 @@
 from .constants import Property
 from .validators import _count_function_parameters, _fatal_error
 
-
 from . import math_engine as me
+from . import entities as en
 
 class DataProbe:
     """A measurement instrument that tracks a spatial target and evaluates mathematical properties.
@@ -14,12 +14,12 @@ class DataProbe:
     listener functions via a callback system.
     """
 
-    def __init__(self, target_region, math_engine: me.MathEngine, measured_property: Property = None):
+    def __init__(self, target_region, target_entity: me.VectorMathEngine | en.VectorField | en.ParticleSystem, measured_property: Property = None):
         """
         Args:
             target_region (SpatialRegion): The spatial entity to be tracked. This object must provide
                 a mechanism to retrieve its current coordinates (e.g., a `center` property or method).
-            math_engine (me.MathEngine): The core mathematical engine responsible for parsing and
+            target_entity (me.VectorMathEngine | en.VectorField | en.ParticleSystem): The core mathematical engine or entity responsible for parsing and
                 evaluating the vector field logic at the given coordinates.
             measured_property (Property, optional): The specific mathematical property to measure
                 at the target's location (e.g., Property.DIVERGENCE). If set to None, the probe evaluates
@@ -50,17 +50,48 @@ class DataProbe:
 
             probe = fr.DataProbe(
                 target_region = interactive_cursor,
-                math_engine = math_engine,
+                target_entity = math_engine, # You can also use a VectorField or ParticleSystem instance here since they also implement the necessary evaluation interface
                 measured_property = fr.Property.VELOCITY
             )
             probe.add_listener(velocity_callback) # Registers the callback to receive velocity updates at the cursor's position
             ```
+
+            A comprehensive example of using DataProbe to display velocity:
+            ```python
+            import FluxRender as fr
+
+            scene = fr.create_workspace()
+
+            def swirling_vortex(x, y):
+                return y, -x
+
+            vector_field = fr.VectorField(swirling_vortex)
+
+            # To pass data (coordinates) to DataProbe we need a region
+            cursor = fr.CursorRegion(always_active=True)
+
+            # We are creating a DataProbe that will measure velocity
+            probe = fr.DataProbe(
+                target_region=cursor,
+                target_entity=vector_field,
+                measured_property=fr.Property.VELOCITY
+            )
+
+            # We display velocity using DynamicText
+            text = fr.DynamicText(text=lambda: f"Velocity: {probe.value}",)
+
+
+            scene.add(vector_field,cursor, probe, text)
+            scene.run()
+            ```
         """
 
         self.target_region = target_region
-        self.math_engine = math_engine
+        self.math_engine = target_entity
         self.measured_property = measured_property
 
+        self.value = 0 if measured_property is not None else (0, 0)  # Initialize value based on property type
+
         self._callbacks = []
 
     def add_listener(self, callback_function):
@@ -108,6 +139,8 @@ class DataProbe:
             probe_y
         )
 
+        self.value = calculated_value if self.measured_property is not None else (vector_dx, vector_dy)
+
         for callback in self._callbacks:
             if self.measured_property is None:
                 callback(vector_dx, vector_dy)

{fluxrender-0.1.4 → fluxrender-0.2.0}/FluxRender/regions.py

@@ -351,7 +351,7 @@ class CursorRegion(SpatialRegion):
 
             probe = fr.DataProbe(
                 target_region=probing_cursor,
-                math_engine=math_engine,
+                target_entity=math_engine,
                 measured_property=fr.Property.VELOCITY
             )
             probe.add_listener(lambda value: print(f"Current velocity at cursor: {value}", end="\\r"))

fluxrender-0.2.0/FluxRender/shortcuts.py

@@ -0,0 +1,302 @@
+import FluxRender.core as cr
+import FluxRender.entities as en
+import FluxRender.ui as ui
+import FluxRender.regions as rg
+import FluxRender.probes as pr
+import FluxRender.math_engine as me
+import FluxRender.constants as ct
+
+from typing import Sequence, Callable, Tuple
+
+
+def create_workspace(
+        resolution: Tuple[int, int] = (1200, 800),
+        x_range: Tuple[float, float] = (-4, 4),
+        y_range: Tuple[float, float] = (-4, 4),
+        window_title: str = "FluxRender Visualization"
+) -> cr.Scene:
+    """
+    Creates a fully configured scene with a ready-to-use coordinate system,
+    axes, and a highly aesthetic double-grid overlay.
+
+    This is an advanced factory function designed to eliminate boilerplate code
+    for users who want a professional workspace out of the box.
+
+    Args:
+        resolution (tuple[int, int]): The dimensions of the application window in pixels. (Default: (1200, 800))
+        x_range (tuple[float, float]): The mathematical boundaries of the X-axis. (Default: (-4, 4))
+        y_range (tuple[float, float]): The mathematical boundaries of the Y-axis. (Default: (-4, 4))
+        window_title (str): The title displayed on the application window. (Default: "FluxRender Visualization")
+
+    Returns:
+        scene (cr.Scene): A fully initialized scene object containing the coordinate system,
+            double grid, and axes, ready for vector fields or particle systems to be added.
+
+    Example:
+        ```python
+        import FluxRender as fr
+        import numpy as np
+
+        workspace = fr.create_workspace()
+
+        def swirling_vortex(x, y):
+            vector_dx = np.sin(y) * x
+            vector_dy = np.cos(x) * y
+            return vector_dx, vector_dy
+
+        vector_field = fr.VectorField(swirling_vortex)
+        particles = fr.ParticleSystem(swirling_vortex)
+
+        workspace.add(particles, vector_field)
+        workspace.run()
+        ```
+    """
+
+    import FluxRender as fr
+
+    coordinate_system = fr.CoordinateSystem(
+        x_range=x_range,
+        y_range=y_range,
+        resolution=resolution,
+        keep_aspect_ratio=True
+    )
+
+    scene = fr.Scene(window_title, coordinate_system)
+
+    # Professional aesthetic: Thick, transparent major grid
+    major_grid = fr.Grid()
+
+    # Professional aesthetic: Thin, dense minor grid
+    minor_grid = fr.Grid(color=(0.6, 0.6, 0.6, 0.2), density=50)
+
+    standard_axes = fr.Axis(
+        color=(0.8, 0.8, 0.8, 1.0),
+        cover_background=True
+    )
+
+    scene.add(minor_grid, major_grid, standard_axes)
+    return scene
+
+def quick_simulate(
+        vec_function: callable,
+        resolution: Tuple[int, int] = (1200, 800),
+):
+    """
+    Instantly generates and runs a complete, interactive simulation from a single vector function.
+
+    This function is the ultimate high-level wrapper. It sets up a standard workspace,
+    injects both a vector field and a particle system based on the provided mathematical
+    function, generates an interactive UI menu for property switching, and starts the render loop.
+
+    Args:
+        vec_function (callable): The mathematical function defining the vector field (e.g., f(x, y, t)).
+        resolution (tuple[int, int]): The dimensions of the application window in pixels. (Default: (1200, 800))
+
+    Returns:
+        scene (cr.Scene): The fully constructed scene. Returned immediately if auto_run is False.
+
+    Example:
+        ```python
+        import FluxRender as fr
+        import numpy as np
+
+        def swirling_vortex(x, y):
+            vector_dx = np.sin(y) * x
+            vector_dy = np.cos(x) * y
+            return vector_dx, vector_dy
+
+        scene = fr.quick_simulate(swirling_vortex)
+        ```
+    """
+
+    import FluxRender as fr
+
+    # region 1. Engine & Entities Setup
+    workspace = fr.create_workspace(resolution)
+
+    math_engine = fr.VectorMathEngine(workspace, vec_function)
+    color_mapper = fr.ColorMapper()
+
+    vector_field = fr.VectorField(math_engine, color_mapper=color_mapper)
+    particles = fr.ParticleSystem(math_engine, color_mapper=color_mapper)
+
+    target_entities = [vector_field, particles]
+    # endregion
+
+    # region 2. Data Probes
+    # Initialize the interactive region tracking the mouse cursor
+    cursor_tracking_region = rg.CursorRegion(always_active=True)
+
+    # Probe for the currently selected scalar property (e.g., Divergence, Curl).
+    # We initialize it with the current property of the vector field.
+    data_probe_property = pr.DataProbe(cursor_tracking_region, math_engine, vector_field.color_property)
+
+    # Probe for the raw mathematical vector value from the math engine
+    data_probe_vector = pr.DataProbe(cursor_tracking_region, math_engine, None)
+    # endregion
+
+    # region 3. Property Switch Construction
+    property_mapping = [
+        ("Component X", ct.Property.COMPONENT_X),
+        ("Component Y", ct.Property.COMPONENT_Y),
+        ("Velocity", ct.Property.VELOCITY),
+        ("Angle", ct.Property.ANGLE),
+        ("Divergence", ct.Property.DIVERGENCE),
+        ("Curl", ct.Property.CURL),
+        ("Jacobian", ct.Property.JACOBIAN),
+        ("Okubo-Weiss", ct.Property.OKUBO_WEISS),
+        ("Convective Acceleration", ct.Property.CONVECTIVE_ACCELERATION),
+    ]
+
+    # UI Styles for the property buttons
+    active_style = ui.UIStyle(
+        background_color=(0.027, 0.212, 0.439, 0.878),
+        hover_background_color=(0.027, 0.212, 0.439, 0.878)
+    )
+    inactive_style = ui.UIStyle(
+        background_color=(0.0, 0.5, 1.0, 0.45),
+        hover_background_color=(0.0, 0.6, 1.0, 0.55),
+    )
+
+    # Internal callback for handling state changes
+    def toggle_property(clicked_button):
+        # Update the visual representation in entities
+        for entity in target_entities:
+            setattr(entity, 'color_property', clicked_button.property)
+
+        # Update the mathematical probe target
+        data_probe_property.measured_property = clicked_button.property
+
+        # Update button visual states
+        for current_button in generated_buttons:
+            is_custom = (current_button.property == ct.Property.CUSTOM)
+            if current_button == clicked_button:
+                current_button.style = active_style
+            else:
+                current_button.style = inactive_style
+
+    generated_buttons = []
+
+    # Dynamically generate buttons based on the mapping
+    for label_text, target_property in property_mapping:
+        is_active = all(getattr(entity, 'color_property', None) == target_property for entity in target_entities)
+
+        initial_style = inactive_style
+        if is_active:
+            initial_style = active_style
+
+        new_button = ui.Button(label_text, toggle_property, style=initial_style)
+        new_button.property = target_property
+        generated_buttons.append(new_button)
+
+    property_switch_container = ui.VBox(
+        spacing=12,
+        common_width=230,
+        common_height=35,
+        style=ui.UIStyle(font_size=16, padding=(12, 12))
+    )
+    property_switch_container.add(*generated_buttons)
+    # endregion
+
+    # region 4. Additional UI Switches (Scale & Mode)
+    color_scale_switch = fr.create_color_scale_switch(workspace, color_mapper, add_to_scene=False)
+    mode_switch = fr.create_mode_switch(workspace, vector_field, add_to_scene=False)
+
+    scale_mode_container = fr.VBox(
+        style=fr.UIStyle(padding=(12, 12)),
+        spacing=12,
+        common_width=230,
+    )
+    scale_mode_container.add(color_scale_switch, mode_switch)
+    # endregion
+
+    # region 5. Dynamic Text Displays
+    def text_property_provider() -> str:
+        current_value = data_probe_property.value
+        # Convert Enum name to a readable format (e.g., "CONVECTIVE_ACCELERATION" -> "Convective Acceleration")
+        formatted_name = data_probe_property.measured_property.name.replace("_", " ").title()
+        return f"{formatted_name}: {current_value:.3f}"
+
+    dynamic_text_property = ui.DynamicText(
+        text=text_property_provider,
+        width=230,
+    )
+
+    def text_vector_provider() -> str:
+        current_value = data_probe_vector.value
+        return f"Vector: ({current_value[0]:.3f}, {current_value[1]:.3f})"
+
+    dynamic_text_vector = ui.DynamicText(
+        text=text_vector_provider,
+        width=230,
+    )
+
+    informations_container = fr.VBox(
+        style=fr.UIStyle(font_size=14, padding=(12, 12)),
+        spacing=12
+    )
+    informations_container.add(dynamic_text_vector, dynamic_text_property)
+    # endregion
+
+    # region 6. Main Layout Assembly
+    # Transparent wrapper linking all panels together vertically
+    main_container_style = fr.UIStyle(visible=False, padding=(0, 0))
+
+    main_wrapper = fr.VBox(
+        position=(10, workspace.height - 10),
+        style=main_container_style,
+        spacing=15
+    )
+    main_wrapper.add(property_switch_container, scale_mode_container, informations_container)
+
+    # Inject all components into the rendering pipeline
+    workspace.add(
+        particles,
+        vector_field,
+        main_wrapper,
+        cursor_tracking_region,
+        data_probe_property,
+        data_probe_vector
+    )
+    # endregion
+
+    workspace.run()
+
+    return workspace
+
+
+
+def as_vector_field(**field_configuration_parameters):
+    """
+    A mathematical decorator that automatically converts a standard Python function
+    into a fully initialized VectorField entity.
+
+    It accepts any number of keyword arguments that the underlying VectorField
+    constructor supports, passing them directly to the instance.
+
+    Example:
+        ```python
+        import FluxRender as fr
+        import numpy as np
+
+        scene = fr.create_workspace()
+
+        @fr.as_vector_field(color_property=fr.Property.CURL)
+        def vector_function(x, y):
+            return np.sin(x) * y, np.cos(y) * x
+
+        scene.add(vector_function)
+        scene.run()
+        ```
+    """
+
+    def wrapper(vec_function: Callable):
+        vector_field = en.VectorField(vec_function, **field_configuration_parameters)
+        return vector_field
+
+    return wrapper
+
+
+
+
+