IBB-Helper 0.4.8.dev28__tar.gz → 0.4.8.dev30__tar.gz

{ibb_helper-0.4.8.dev28/src/IBB_Helper.egg-info → ibb_helper-0.4.8.dev30}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: IBB_Helper
-Version: 0.4.8.dev28
+Version: 0.4.8.dev30
 Summary: Helper functions for symbolic math, matrix visualization, and plotting
 Author-email: "University of Stuttgart, Institute for Structural Mechanics (IBB)" <mvs@ibb.uni-stuttgart.de>
 License-Expression: BSD-3-Clause

{ibb_helper-0.4.8.dev28 → ibb_helper-0.4.8.dev30}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "IBB_Helper"
-version = "0.4.8.dev28"
+version = "0.4.8.dev30"
 description = "Helper functions for symbolic math, matrix visualization, and plotting"
 readme = "README.md"
 license = "BSD-3-Clause"

ibb_helper-0.4.8.dev30/src/IBB_Helper/animate.py

@@ -0,0 +1,249 @@
+import numpy as np
+import sympy as sp
+import matplotlib.pyplot as plt
+import matplotlib.animation
+from sympy import latex, Matrix
+
+def animate(exprs, var, 
+            # --- Labels & Text ---
+            labels=None, title="Animation", xlabel="x", ylabel="y",
+            # --- Styling ---
+            line_styles=None, colors=None, linewidth=2, 
+            # --- Limits ---
+            xlim=None, ylim=None, 
+            # --- Animation Config ---
+            animation_time=5000, frames=100, resolution=400, show=True):
+
+    """
+    Animates 2D curves from symbolic expressions or numeric datasets using Matplotlib.
+
+    Parameters:
+        exprs          : Expression, tuple, or list of expressions (symbolic, parametric, or numeric data)
+        var            : Symbol or tuple defining variable/range, or array mode ('array', x_values)
+        
+        # --- Labels ---
+        labels         : Curve labels (strings or SymPy expressions, LaTeX supported) (default=None)
+        title          : Plot title (default="Animation")
+        xlabel         : X-axis label (default="x")
+        ylabel         : Y-axis label (default="y")
+        
+        # --- Styling ---
+        line_styles    : Line styles for each curve (default=None -> solid)
+        colors         : Colors for each curve (default=None -> Matplotlib cycle)
+        linewidth      : Line width(s) as int or list (default=2)
+        
+        # --- Limits ---
+        xlim           : X-axis limits as (min, max) (default=None -> auto)
+        ylim           : Y-axis limits as (min, max) (default=None -> auto)
+        
+        # --- Animation Config ---
+        animation_time : Total animation duration in milliseconds (default=5000)
+        frames         : Number of animation frames (default=100)
+        resolution     : Number of evaluation points for symbolic expressions (default=400)
+        show           : Whether to display the animation (default=True)
+
+    Returns:
+        matplotlib.animation.FuncAnimation
+            The animation object
+    """
+
+    # Configuration
+    plt.rcParams["animation.html"] = "jshtml"
+    plt.rcParams['figure.dpi'] = 150
+    plt.ioff()
+
+    # Label Formatting
+    def _smart_label(lbl):
+        """Converts strings or SymPy objects to LaTeX formatted strings."""
+        if lbl is None:
+            return None
+        if isinstance(lbl, str):
+            # Check for LaTeX characters
+            if any(c in lbl for c in ['_', '^', '\\', '$']):
+                return f"${lbl}$" if '$' not in lbl else lbl
+            return lbl
+        # Convert SymPy expression to LaTeX
+        return f"${latex(lbl)}$"
+
+    # Data Preparation
+    def _prepare_data(raw_exprs, variable_def):
+        """
+        Parses inputs (Symbolic/Numeric) and generates consistent (x, y) arrays.
+        """
+        # Normalize inputs to lists
+        if not isinstance(raw_exprs, list):
+            expr_list = [raw_exprs]
+        else:
+            expr_list = raw_exprs
+
+        # Determine symbol and range
+        is_sympy_mode = True
+        
+        if isinstance(variable_def, tuple):
+            if variable_def[0] == 'array':
+                is_sympy_mode = False
+                x_vals_sample = variable_def[1]
+                # If array mode, frames usually equals array length
+                nonlocal frames 
+                frames = len(x_vals_sample) 
+                x_sym = None
+            else:
+                x_sym = variable_def[0]
+                x_range = variable_def[1]
+                x_vals_sample = np.linspace(float(x_range[0]), float(x_range[1]), frames)
+        else:
+            x_sym = variable_def
+            x_range = (-1, 1)
+            x_vals_sample = np.linspace(float(x_range[0]), float(x_range[1]), frames)
+
+        prepared_data = []
+
+        for expr in expr_list:
+            # Handle SymPy Matrices
+            if isinstance(expr, Matrix):
+                expr = np.array(expr).astype(np.float64).flatten()
+            
+            # Handle Parametric or Data Tuples (x, y)
+            if isinstance(expr, (tuple, list)) and len(expr) == 2:
+                x_comp, y_comp = expr
+                
+                # Symbolic Parametric
+                if isinstance(x_comp, sp.Basic) or isinstance(y_comp, sp.Basic):
+                    if is_sympy_mode:
+                        f_x = sp.lambdify(x_sym, x_comp, modules='numpy')
+                        f_y = sp.lambdify(x_sym, y_comp, modules='numpy')
+                        x_data = f_x(x_vals_sample)
+                        y_data = f_y(x_vals_sample)
+                    else:
+                         # Fallback if mixed types (shouldn't happen often)
+                        x_data, y_data = x_comp, y_comp
+                else:
+                    # Numeric Data or Constants
+                    x_data, y_data = x_comp, y_comp
+                    
+                    # specific check for constant arrays
+                    is_x_array = hasattr(x_data, '__len__')
+                    is_y_array = hasattr(y_data, '__len__')
+
+                    if is_x_array and not is_y_array:
+                        y_data = np.full_like(x_data, y_data)
+                    elif not is_x_array and is_y_array:
+                        x_data = np.full_like(y_data, x_data)
+
+                prepared_data.append((np.array(x_data), np.array(y_data)))
+
+            # Handle Single Expressions (y = f(x))
+            else:
+                expr = sp.sympify(expr)
+                
+                # Constant function check
+                if is_sympy_mode and not expr.has(x_sym):
+                    y_vals = np.full_like(x_vals_sample, float(expr))
+                else:
+                    if is_sympy_mode:
+                        f = sp.lambdify(x_sym, expr, modules='numpy')
+                        try:
+                            y_vals = f(x_vals_sample)
+                            # Handle case where lambdify returns a scalar for vector input
+                            if np.isscalar(y_vals): 
+                                y_vals = np.full_like(x_vals_sample, y_vals)
+                        except Exception:
+                            # Fallback for complex constant expressions
+                            y_vals = np.full_like(x_vals_sample, float(expr))
+                    else:
+                        y_vals = np.array(expr).flatten()
+                
+                y_vals = np.array(y_vals).flatten()
+                prepared_data.append((x_vals_sample, y_vals))
+                
+        return prepared_data
+
+    # Animation Logic
+    def _create_animation_object(plot_data):
+        """Sets up the figure, axes, and FuncAnimation object."""
+        
+        # 1. Normalize Styling
+        n_plots = len(plot_data)
+        
+        # Thickness
+        if isinstance(linewidth, (int, float)):
+            lw_list = [linewidth] * n_plots
+        else:
+            lw_list = linewidth
+            
+        # Limits Calculation (if None)
+        nonlocal xlim, ylim
+        if xlim is None:
+            all_x = np.concatenate([d[0] for d in plot_data])
+            x_min, x_max = np.min(all_x), np.max(all_x)
+            dx = x_max - x_min if x_max != x_min else 1.0
+            xlim = (x_min - 0.05 * dx, x_max + 0.05 * dx)
+            
+        if ylim is None:
+            all_y = np.concatenate([d[1] for d in plot_data])
+            y_min, y_max = np.min(all_y), np.max(all_y)
+            dy = y_max - y_min if y_max != y_min else 1.0
+            ylim = (y_min - 0.1 * dy, y_max + 0.1 * dy)
+
+        # 2. Setup Figure
+        fig, ax = plt.subplots(figsize=(10, 6))
+
+        # 3. Update Function
+        def _update_frame(frame):
+            ax.clear()
+            
+            # Use 'frame + 1' to ensure we plot at least one point
+            idx = int(frame + 1)
+            
+            for i, (x_data, y_data) in enumerate(plot_data):
+                # Safe Styling Retrieval
+                style = line_styles[i] if line_styles and i < len(line_styles) else 'solid'
+                color = colors[i] if colors and i < len(colors) else None
+                
+                # Label Handling
+                raw_lbl = labels[i] if labels and i < len(labels) else None
+                lbl = _smart_label(raw_lbl)
+
+                # Slice data for animation effect
+                # Ensure we don't index out of bounds if frames > data length
+                curr_x = x_data[:min(idx, len(x_data))]
+                curr_y = y_data[:min(idx, len(y_data))]
+
+                ax.plot(curr_x, curr_y,
+                       label=lbl,
+                       linestyle=style,
+                       color=color,
+                       linewidth=lw_list[i] if i < len(lw_list) else 2)
+
+            # Apply Layout Settings
+            ax.set_xlim(xlim)
+            ax.set_ylim(ylim)
+            ax.set_title(_smart_label(title))
+            ax.set_xlabel(_smart_label(xlabel))
+            ax.set_ylabel(_smart_label(ylabel))
+            
+            if labels:
+                ax.legend()
+            ax.grid(True, alpha=0.3)
+
+        # 4. Create Animation
+        interval = animation_time / frames
+        anim = matplotlib.animation.FuncAnimation(
+            fig, _update_frame, frames=frames, interval=interval, repeat=True
+        )
+        
+        return anim
+
+    # Main Execution
+    
+    # 1. Prepare Data
+    data = _prepare_data(exprs, var)
+    
+    # 2. Create Animation
+    anim_obj = _create_animation_object(data)
+    
+    # 3. Display
+    if not show:
+        plt.close()
+        
+    return anim_obj

{ibb_helper-0.4.8.dev28 → ibb_helper-0.4.8.dev30}/src/IBB_Helper/combine_plots.py

@@ -3,9 +3,20 @@ import plotly.graph_objects as go
 import copy
 import numpy as np
 
-def combine_plots(plot_list, labels=None, line_styles=None, colors=None,
-                  swap_axes=False, show=True, grid=False,
-                  xlim=None, ylim=None, title=None, xlabel=None, ylabel=None, width=800, height=700):
+def combine_plots(plot_list,
+                # --- Plot Labels ---
+                title=None, xlabel=None, ylabel=None, labels=None,
+                # --- Styling ---
+                colors=None, line_styles=None,
+                # --- Axis Options ---
+                swap_axes=False, grid=False,
+                # --- Limits ---
+                xlim=None, ylim=None,
+                # --- Display ---
+                show=True,
+                # --- Figure Size ---
+                width=800, height=700):
+
     """
     Combines multiple Matplotlib Axes or Plotly Figures into a single plot while preserving styles.
 

ibb_helper-0.4.8.dev30/src/IBB_Helper/display.py

@@ -0,0 +1,65 @@
+import numpy                as    np
+import sympy                as    sp
+from   sympy                import latex
+import IPython.display      as    ipy
+
+def display(obj, name=None, evalf=False, prec=5, mathrm=False):
+    """
+    Converts vectors/numbers/matrices to LaTeX with optional simplification using internal helpers.
+
+    Parameters:
+        obj     : Input (SymPy or NumPy object)
+        name    : Name used for display
+        evalf   : If True, evaluates to decimal form before display (default: False)
+        prec    : Evaluate the given formula to an accuracy of prec digits (default: 5)
+        mathrm  : Boolean to display as Roman text
+
+    Returns:
+        None
+    """
+    # Safe Rounding Helper
+    def _safe_round(x):
+        try:
+            x = sp.sympify(x)
+            return x.replace(
+                lambda a: isinstance(a, sp.Float),
+                lambda a: sp.Float(round(float(a), prec))
+            )
+        except (TypeError, ValueError):
+            return x
+
+    # Object Preparation
+    def _prepare_object(raw_obj):
+        # 1. Standardization: Convert to SymPy types
+        if isinstance(raw_obj, np.ndarray):
+            sym_obj = sp.Matrix(raw_obj)
+        elif isinstance(raw_obj, (sp.Matrix, list)):
+            sym_obj = sp.Matrix(raw_obj)
+        elif isinstance(raw_obj, sp.NDimArray):
+            sym_obj = raw_obj
+        else:
+            sym_obj = sp.sympify(raw_obj)
+
+        # 2. Evaluation: Apply rounding if requested
+        if evalf:
+            if hasattr(sym_obj, 'applyfunc'):
+                return sym_obj.applyfunc(_safe_round)
+            return _safe_round(sym_obj)
+        
+        return sym_obj
+
+    # Rendering
+    def _render(processed_obj):
+        latex_str = latex(processed_obj)
+
+        if mathrm:
+            latex_str = rf"\mathrm{{{latex_str}}}"
+
+        if name is None:
+            ipy.display(ipy.Math(latex_str))
+        else:
+            ipy.display(ipy.Math(f"{name} = {latex_str}"))
+
+    # Main Execution
+    final_obj = _prepare_object(obj)
+    _render(final_obj)

ibb_helper-0.4.8.dev30/src/IBB_Helper/display_eigen.py

@@ -0,0 +1,127 @@
+import numpy                as    np
+import sympy                as    sp
+from   sympy                import latex
+import IPython.display      as    ipy
+
+def display_eigen(A, 
+                # --- Labeling & Formatting ---
+                name="Matrix", evalf=False, prec=5, 
+                # --- Output Control ---
+                show="both", output="default", return_data=False, reverse=False):
+
+    """
+    Computes and displays the eigenvalues and eigenvectors of a matrix A using internal sub-functions.
+
+    Parameters:
+        A           : Square matrix (SymPy Matrix or NumPy ndarray)
+        name        : Label used for the matrix (default="Matrix")
+        evalf       : If True, show decimal values (default=False)
+        prec        : Accuracy of decimal evaluation (default: 5)
+        show        : What to display ("both", "eigvals", "eigvecs", or "none") (default="both")
+        output      : How to display ("default", "compact", "Maple") (default="default")
+        return_data : If True, returns eigenvalues and eigenvectors (default=False)
+        reverse     : If True, sorts eigenvalues in descending order (default=False)
+
+    Returns (if return_data=True):
+        - sp.Matrix: Column vector of eigenvalues
+        - sp.Matrix: Matrix of eigenvectors (stacked columns)
+    """
+
+    threshold = 10**(-10)
+
+    # Safe Evaluation
+    def _safe_eval(x):
+        try:
+            val = x.evalf(prec)
+            if abs(val) < threshold:
+                return sp.Integer(0)
+            return round(float(val), prec)
+        except (TypeError, ValueError):
+            return x
+
+    # Compute & Process Data
+    def _compute_eigen_data(matrix_in):
+        # Convert NumPy array if needed
+        if isinstance(matrix_in, np.ndarray):
+            matrix_in = sp.Matrix(matrix_in)
+
+        # Compute raw eigen data: list of (eigenval, multiplicity, [eigenvecs])
+        raw_data = sorted(matrix_in.eigenvects(), key=lambda x: x[0], reverse=reverse)
+        
+        vals_clean = []
+        vecs_clean = []
+
+        for eigval, mult, vects in raw_data:
+            for i in range(mult):
+                v_raw = vects[i]
+                
+                # Normalize vector by its largest element for cleaner display
+                max_val = max(v_raw, key=lambda x: abs(x.evalf()))
+                v_norm = v_raw / max_val
+
+                # Apply numerical formatting if requested
+                if evalf:
+                    val_processed = _safe_eval(eigval)
+                    vec_processed = v_norm.applyfunc(_safe_eval)
+                else:
+                    val_processed = eigval
+                    vec_processed = v_norm
+                
+                vals_clean.append(val_processed)
+                vecs_clean.append(vec_processed)
+                
+        return vals_clean, vecs_clean
+
+    # Render Output
+    def _render_display(vals, vecs):
+        # Header
+        if show == "both":
+            ipy.display(ipy.Math(f"\\text{{Eigenvalues and Eigenvectors of }} {name}:"))
+            
+            if output == "default":
+                for i, (val, vec) in enumerate(zip(vals, vecs)):
+                    latex_str = f"\\lambda_{{{i+1}}} = {latex(val)}, v_{{{i+1}}} = {latex(vec)} \\qquad"
+                    ipy.display(ipy.Math(latex_str))
+            
+            elif output == "compact":
+                for i, (val, vec) in enumerate(zip(vals, vecs)):
+                    # Transpose vector for compact row view
+                    latex_str = f"\\lambda_{{{i+1}}} = {latex(val)}, \\quad v_{{{i+1}}} = {latex(vec.T)}"
+                    ipy.display(ipy.Math(latex_str))
+            
+            elif output == "maple":
+                # Vector of eigenvalues
+                ipy.display(ipy.Math(f"\\lambda = {latex(sp.Matrix(vals))}"))
+                # Matrix of eigenvectors
+                V_matrix = sp.Matrix.hstack(*vecs)
+                ipy.display(ipy.Math(f"v = {latex(V_matrix)}"))
+
+        elif show == "eigvals":
+            ipy.display(ipy.Math(f"\\text{{Eigenvalues of }} {name}: \\quad \\lambda = {latex(sp.Matrix(vals))}"))
+
+        elif show == "eigvecs":
+            V_matrix = sp.Matrix.hstack(*vecs)
+            ipy.display(ipy.Math(f"\\text{{Eigenvectors of }} {name}: \\quad v = {latex(V_matrix)}"))
+
+    # Main Execution Flow
+    
+    # Validation
+    show_opt = show.lower()
+    out_opt = output.lower()
+    if show_opt not in ["both", "eigvals", "eigvecs", "none"]:
+        raise ValueError(f"Invalid 'show' option: {show}")
+    if out_opt not in ["default", "compact", "maple"]:
+        raise ValueError(f"Invalid 'output' option: {output}")
+
+    # Computation
+    eig_vals, eig_vecs = _compute_eigen_data(A)
+
+    # Display
+    if show_opt != "none":
+        _render_display(eig_vals, eig_vecs)
+
+    # Return Data
+    if return_data:
+        return sp.Matrix(eig_vals), sp.Matrix.hstack(*eig_vecs)
+    
+    return None

ibb_helper-0.4.8.dev30/src/IBB_Helper/display_matrix.py

@@ -0,0 +1,59 @@
+import numpy                as    np
+import sympy                as    sp
+from   sympy                import latex
+from   IPython.display      import Math, display
+
+def display_matrix(matrix, name="Matrix", r=8, c=8, evalf=False, prec=5, mathrm=True):
+    """
+    Displays a truncated matrix with optional numerical evaluation and rational simplification.
+    
+    Parameters:
+        matrix  : Input matrix (NumPy array, SymPy Matrix, or list)
+        name    : Display name (default: "Matrix")
+        r       : Max rows to display (default: 8)
+        c       : Max columns to display (default: 8)
+        evalf   : If True, apply numerical evaluation (default: False)
+        prec    : Evaluate the given formula to an accuracy of prec digits
+        mathrm  : Boolean to display as Roman text (default: True)
+
+    Returns:
+        None
+    """
+
+    # Matrix Preparation
+    def _prepare_matrix(raw_mat):
+        if isinstance(raw_mat, (np.ndarray, list)):
+            return sp.Matrix(raw_mat)
+        return raw_mat
+
+    # Processing (Truncation & Evaluation)
+    def _process_submatrix(full_mat):
+        # Truncate
+        sub = full_mat[:min(r, full_mat.rows), :min(c, full_mat.cols)]
+        
+        # Evaluate
+        if evalf:
+            return sub.applyfunc(lambda x: x.evalf(prec))
+        return sub
+
+    # Rendering
+    def _render(processed_sub, original_rows, original_cols):
+        # Generate LaTeX with spacing adjustment
+        expr = latex(processed_sub).replace(r'\\', r'\\[5pt]')
+        
+        if mathrm:
+            expr = rf"\mathrm{{{expr}}}"
+        
+        # Display Main Equation
+        label = rf"\large {name} =" if name else r"\large"
+        display(Math(rf"{label} {expr}"))
+
+        # Display Truncation Message
+        if original_rows > r or original_cols > c:
+            msg = rf"\text{{... Truncated to first {r}x{c} out of {original_rows}x{original_cols} matrix}}"
+            display(Math(msg))
+
+    # Main Execution
+    sym_matrix = _prepare_matrix(matrix)
+    sub_matrix = _process_submatrix(sym_matrix)
+    _render(sub_matrix, sym_matrix.rows, sym_matrix.cols)