simstack 2.0.1__py3-none-any.whl

simstack/static/docs/_sources/ui_documentation.rst.txt

@@ -0,0 +1,272 @@
+.. _using-gui-section:
+
+Graphical User Interface
+========================
+
+SimStack II provides a modern web-based user interface for managing scientific workflows, data analysis, and visualization.
+This guide will walk you through the main features and how to use them effectively.
+
+.. Note:: The GUI does not auto-update and has not been tested on mobile devices.
+
+.. figure:: resources/navigation.png
+   :align: center
+   :alt: SimStack Navigation Bar
+
+   The main navigation bar at the top of the interface
+
+The navigation bar at the top provides access to different sections of the application,
+including the
+
+* **Tasks** to inspect jobs and their results (also: Simstack II icon)
+* **Submit Panel** to submit new workflows (plus icon)
+* **Health Dashboard** for the status of the runners and running remote jobs.
+* **Editor** work in progress
+* **Profile** for user account settings.
+
+Dashboard
+---------
+
+.. figure:: resources/dashboard.png
+   :align: center
+   :alt: SimStack Dashboard
+
+   The main dashboard showing workflow tasks and their status
+
+The dashboard is your central hub for monitoring and managing workflow tasks. It displays a table of all your tasks.
+Rows are color-coded based on their status for easy identification.
+
+* **Yellow**: Submitted
+* **Blue**: Running
+* **Green**: Completed
+* **Red**: Failed
+* **White**: Timed out
+
+You can:
+
+* **Search and Filter**: Search by name or custom name, and filter by task type, category, status, or resource
+* **Sorting**: Click on column headers to sort tasks by name, status, or creation date
+* **Bulk Operations**: Select multiple tasks to perform batch operations like deletion
+* **Task Details**: Click on a task name to view its details, inputs, outputs, and logs
+* **Child Tasks**: Expand tasks to see any child tasks that were spawned during execution (recursively)
+
+.. Note:: Simstack II will recover the results of tasks with the same inputs (not parameters), the same task may therefore occur as a subtaks of multiple parent tasks.
+
+Key columns in the dashboard include:
+
+* **Name**: The workflow node name -- this is the name of the function that generated the task (Click for details)
+* **Custom Name**: User-defined name for the task
+* **Category**: Task category for organization
+* **Status**: Current status (running, completed, failed, etc.)
+* **Resource**: Computational resource used for the task
+* **Created/Started**: Timestamps for task creation and execution
+* **Actions**: Buttons for viewing, editing, or deleting tasks
+
+Viewing Task Details
+--------------------
+
+.. figure:: resources/task_details.png
+   :align: center
+   :alt: Task Details View
+
+   Detailed view of a workflow task showing parameters, outputs, and logs
+
+When you click on a task in the dashboard, you'll be taken to the task details page, which provides:
+
+* **Task Information**: Name, ID, status, and timestamps
+* **Inputs**: Input parameters used for the task
+* **Results**: Results and artifacts generated by the task
+* **Artifacts**: Tables and visualizations (if available) that can be created from the task outputs **after** the task has completed **without rerunning the task**
+  This powerful feature allows users to analyze and visualize data in ways that were not initially anticipated when the workflow was created.
+* **Info Items**: All result data of the tasks should be presented in the result section. However, in particular, while debugging, it
+  is useful to have access to input and output files that were used/generated by the task. These files are available in the "Info Items" section for
+  viewing and downloading.
+* **Logs**: Execution logs for debugging and monitoring. There are three kinds of logs:
+    1. **Task Logs**: Logs generated by the specific workflow task, offering detailed information about the task's execution process, including any errors or warnings encountered.
+       In most cases these logs are the most relevant for users to understand the behavior of their workflows.
+
+    1. **System Logs**: Logs generated by the Simstack system itself, providing insights into the overall operation and any system-level issues.
+    2. **Runner Logs**: Logs produced by the resource runner that executed the task, which can help diagnose issues related to the computational environment or resource allocation.
+
+
+You can navigate through different tabs to access various aspects of the task data.
+
+.. figure:: resources/artifacts.png
+   :align: center
+   :alt: Example Chart Artifact
+
+   Example image artifact created by ag-charts. The user can interaction with the data and download it as needed.
+
+.. include:: submit.rst
+
+
+Health Dashboard
+----------------
+
+.. figure:: resources/health_dashboard.png
+   :align: center
+   :alt: Health Dashboard
+
+   The health dashboard showing system status and resource utilization
+
+The Health Dashboard provides real-time monitoring of system components and resource utilization. It displays:
+
+* **Runner Events**: Status updates from resource runners
+* **System Health**: Overall health status of different components
+* **Resource Utilization**: CPU, memory, and storage usage statistics
+
+This dashboard is particularly useful for administrators and users who need to monitor the performance of their workflows and the system as a whole.
+
+Data Visualization
+-----------------
+
+.. figure:: resources/data_visualization.png
+   :align: center
+   :alt: Data Visualization
+
+   Interactive data visualization using AG-Charts
+
+SimStack II provides powerful data visualization capabilities using AG-Charts:
+
+* **Interactive Charts**: Zoom, pan, and hover for details
+* **Multiple Chart Types**: Line, bar, scatter, pie charts, and more
+* **Customization**: Adjust colors, labels, and other visual properties
+* **Export**: Save charts as images for reports or presentations
+
+To access visualizations:
+
+1. Navigate to a completed task
+2. Select the "Visualization" tab
+3. Choose from available chart types based on the task's outputs
+4. Interact with the chart to explore the data
+
+Data Tables
+-----------
+
+.. figure:: resources/data_tables.png
+   :align: center
+   :alt: Data Tables
+
+   Interactive data tables using AG-Grid
+
+For tabular data, SimStack II uses AG-Grid to provide interactive tables with:
+
+* **Sorting and Filtering**: Click column headers to sort, use filters to find specific data
+* **Column Resizing**: Adjust column widths by dragging
+* **Row Selection**: Select rows for export or further analysis
+* **Pagination**: Navigate through large datasets with ease
+* **Export**: Download data as CSV or Excel files
+
+User Account Management
+-----------------------
+
+.. figure:: resources/user_account.png
+   :align: center
+   :alt: User Account Management
+
+   User account settings and preferences
+
+SimStack II provides user account management features:
+
+* **Login/Logout**: Secure authentication system
+* **Registration**: Create a new account with email verification
+* **Profile Settings**: Update personal information and preferences
+* **API Tokens**: Generate and manage API tokens for programmatic access
+
+Tips for Effective Use
+---------------------
+
+* **Custom Names**: Give your tasks meaningful custom names for easier identification
+* **Categories**: Use categories to organize related tasks
+* **Regular Monitoring**: Check the Health Dashboard periodically to ensure system health
+* **Batch Operations**: Use bulk selection for efficient management of multiple tasks
+* **Search and Filters**: Utilize search and filters to quickly find specific tasks
+
+.. _writing-gui-section:
+
+Exposing Workflows in the GUI
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Concept
+-------
+
+The components of the graphical user interface are illustrated below. With a
+Next-js frontend, we use one of the most modern web-frameworks with a large
+community supporting a plethora of packages.
+
+.. figure:: resources/GUI\ Concept.webp
+   :align: center
+   :alt: GUI Concept Design
+
+   Overview of the graphical user interface concept
+
+The challenge in Simstack II is to exploit the features of Next-JS frontend
+without forcing the developer to write Next-JS or server components. In
+Simstack II each user has his/her own MongoDB database, there is an
+additional database used exclusively for authentication.
+
+.. note:: Only one instance of a mongodb database server, of the fastapi
+   server and of the next-js frontend is required per installation.
+
+
+The workflow developer customizes the appearance of workflows for submission,
+data analysis and data visualization using three main mechanisms:
+
+* `React JSON Schema Form <https://rjsf-team.github.io/react-jsonschema-form/>`_
+* `AG-Grid <https://www.ag-grid.com/>`_ is used to generate interactive tables (via Artifacts)
+* `AG-Charts <https://charts.ag-grid.com/>`_ is used to generate interactive graphs (via Artifacts)
+
+Customizing Simstack Models
+---------------------------
+
+.. note:: General information about Simstack models
+
+The JSON Schema and UI Schema are used to define the structure and appearance of forms in the GUI. The JSON Schema defines the data structure, while the UI Schema controls how the form is rendered.
+
+**JSON Schema Example:**
+
+.. code-block:: json
+
+    {
+      "type": "object",
+      "required": ["name", "resource"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "title": "Workflow Name"
+        },
+        "resource": {
+          "type": "string",
+          "title": "Computational Resource",
+          "enum": ["local", "cluster", "cloud"]
+        },
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "iterations": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 1000,
+              "default": 100,
+              "title": "Number of Iterations"
+            }
+          }
+        }
+      }
+    }
+
+**UI Schema Example:**
+
+.. code-block:: json
+
+    {
+      "resource": {
+        "ui:widget": "select"
+      },
+      "parameters": {
+        "iterations": {
+          "ui:widget": "range"
+        }
+      }
+    }
+
+These schemas are used to generate dynamic forms for workflow submission and editing.