einsteinengine 0.5.0__tar.gz

einsteinengine-0.5.0/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: einsteinengine
+Version: 0.5.0
+Summary: A high-performance, object-oriented symbolic tensor engine for General Relativity.
+Author-email: Rafael Salazar <rsalazard2005@gmail.com>
+Project-URL: Homepage, https://github.com/RSalazarD/EinsteinEngine
+Project-URL: Bug Tracker, https://github.com/RSalazarD/EinsteinEngine/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: sympy>=1.12
+Requires-Dist: symengine>=0.11.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: scipy>=1.10.0
+
+#  EinsteinEngine
+
+**A high-performance, object-oriented symbolic tensor engine for General Relativity, powered by Python and C++.**
+
+EinsteinEngine is designed to solve the performance bottlenecks of traditional pure-Python symbolic calculators. By wrapping `SymEngine` (C++) backend inside a Python API, it computes Christoffel Symbols, Riemann Tensors, and other complex relativistic structures faster than standard pure Python libraries.
+
+---
+
+## Key Features
+
+* **⚡ C++ Backend:** Mathematical heavy-lifting (partial derivatives, massive tensor contractions) is routed directly to `SymEngine`, bypassing Python's native performance limits.
+* **🧠 Smart Memoization:** Built-in memory caching prevents redundant calculations of highly complex objects like inverse metric tensors.
+* **📦 Clean Object-Oriented API:** Complex tensor pipelines are reduced to a few lines of readable code using class inheritance.
+* **🛡️ Exact Mathematics:** Built to handle rational numbers securely, preventing floating-point contamination and ensuring textbook-perfect algebraic simplifications.
+
+---
+
+## Quick Start
+
+EinsteinEngine calculates the entire Riemann Curvature Tensor of a Black Hole in just two lines of code:
+
+```python
+import sympy as sp
+from einsteinpy.symbolic.metric import MetricTensor
+from einsteinpy.symbolic.riemann import RiemannCurvatureTensor
+
+# 1. Define your symbols and metric array
+t, r, theta, phi = sp.symbols('t r theta phi', real=True)
+M = sp.symbols('M', real=True)
+
+g_schwarzschild = [
+    [-(1 - 2*M/r), 0, 0, 0],
+    [0, 1/(1 - 2*M/r), 0, 0],
+    [0, 0, r**2, 0],
+    [0, 0, 0, r**2 * sp.sin(theta)**2]
+]
+
+# 2. Run the EinsteinEngine Pipeline
+metric = MetricTensor(g_schwarzschild, [t, r, theta, phi], name="Schwarzschild")
+riemann = RiemannCurvatureTensor.from_metric(metric)
+
+# 3. Extract exact, simplified textbook results
+print(riemann.get_component(1, 0, 1, 0))
+# Output: 2*M*(2*M - r)/r**4

einsteinengine-0.5.0/README.md

@@ -0,0 +1,44 @@
+#  EinsteinEngine
+
+**A high-performance, object-oriented symbolic tensor engine for General Relativity, powered by Python and C++.**
+
+EinsteinEngine is designed to solve the performance bottlenecks of traditional pure-Python symbolic calculators. By wrapping `SymEngine` (C++) backend inside a Python API, it computes Christoffel Symbols, Riemann Tensors, and other complex relativistic structures faster than standard pure Python libraries.
+
+---
+
+## Key Features
+
+* **⚡ C++ Backend:** Mathematical heavy-lifting (partial derivatives, massive tensor contractions) is routed directly to `SymEngine`, bypassing Python's native performance limits.
+* **🧠 Smart Memoization:** Built-in memory caching prevents redundant calculations of highly complex objects like inverse metric tensors.
+* **📦 Clean Object-Oriented API:** Complex tensor pipelines are reduced to a few lines of readable code using class inheritance.
+* **🛡️ Exact Mathematics:** Built to handle rational numbers securely, preventing floating-point contamination and ensuring textbook-perfect algebraic simplifications.
+
+---
+
+## Quick Start
+
+EinsteinEngine calculates the entire Riemann Curvature Tensor of a Black Hole in just two lines of code:
+
+```python
+import sympy as sp
+from einsteinpy.symbolic.metric import MetricTensor
+from einsteinpy.symbolic.riemann import RiemannCurvatureTensor
+
+# 1. Define your symbols and metric array
+t, r, theta, phi = sp.symbols('t r theta phi', real=True)
+M = sp.symbols('M', real=True)
+
+g_schwarzschild = [
+    [-(1 - 2*M/r), 0, 0, 0],
+    [0, 1/(1 - 2*M/r), 0, 0],
+    [0, 0, r**2, 0],
+    [0, 0, 0, r**2 * sp.sin(theta)**2]
+]
+
+# 2. Run the EinsteinEngine Pipeline
+metric = MetricTensor(g_schwarzschild, [t, r, theta, phi], name="Schwarzschild")
+riemann = RiemannCurvatureTensor.from_metric(metric)
+
+# 3. Extract exact, simplified textbook results
+print(riemann.get_component(1, 0, 1, 0))
+# Output: 2*M*(2*M - r)/r**4

einsteinengine-0.5.0/einsteinengine/symbolic/christoffel.py

@@ -0,0 +1,39 @@
+import symengine as se
+from einsteinengine.symbolic.connection import BaseConnection
+class ChristoffelSymbols(BaseConnection):
+    """
+    Computes the Christoffel Symbols of the second kind (Gamma^lambda_{mu nu})
+    optimized via SymEngine backend processing.
+    """
+    @classmethod
+    def from_metric(cls, metric, verbose=False):
+        """
+        Computes the Christoffel Symbols of the second kind (Gamma^lambda_{mu nu})
+        optimized via SymEngine backend processing.
+        """
+        if verbose:
+            print(f"Computing Christoffel Symbols for '{metric.name}' in C++...")
+            
+        g = metric._data
+        g_inv = metric.inv()._data
+        syms = metric.syms
+        dims = metric.dims
+        
+        # Initialize a 3D grid structure for Gamma (4x4x4)
+        Gamma = [[[se.sympify(0) for _ in range(dims)] for _ in range(dims)] for _ in range(dims)]
+        
+        # Heavy-lifting partial derivative loops triggered directly in C++
+        for lambda_ in range(dims):
+            for mu in range(dims):
+                for nu in range(dims):
+                    tmp_sum = se.sympify(0)
+                    for sigma in range(dims):
+                        term1 = se.diff(g[nu][sigma], syms[mu])
+                        term2 = se.diff(g[mu][sigma], syms[nu])
+                        term3 = se.diff(g[mu][nu], syms[sigma])
+                        tmp_sum += g_inv[lambda_][sigma] * (term1 + term2 - term3)
+                    
+                    Gamma[lambda_][mu][nu] = se.Rational(1, 2) * tmp_sum
+                    
+        # Devuelve instanciando la nueva clase madre BaseConnection
+        return cls(Gamma, syms, config="ull", name=f"Christoffel_{metric.name}", verbose=verbose)

einsteinengine-0.5.0/einsteinengine/symbolic/connection.py

@@ -0,0 +1,111 @@
+from einsteinengine.symbolic.core import BaseRelativityObject
+
+class BaseConnection(BaseRelativityObject):
+    """
+    Base class for mathematical Connections (e.g., Levi-Civita, Spin, Affine).
+    Inherits coordinate and array management from BaseRelativityObject.
+    
+    IMPORTANT: Connections are NOT tensors. They do not transform homogeneously 
+    under coordinate changes, and operations like raising/lowering all indices 
+    using the metric do not apply in the standard tensorial way.
+    """
+    def __init__(self, arr, syms, config="ull", name="GenericConnection", verbose=False):
+        # 1. Delegate the heavy lifting to the parent object
+        super().__init__(arr, syms, name=name, verbose=verbose)
+        
+        # 2. Connection index configuration (usually one upper, two lower)
+        self.config = config
+        
+        # 3. Validation: Connections in standard GR are 3-index objects
+        if self._data and isinstance(arr, list):
+            rank = self._calculate_rank(arr)
+            if rank != 3:
+                raise ValueError(f"A connection must have exactly 3 indices. Got {rank}.")
+
+        if self.verbose:
+            print(f"[{self.name}] Connection initialized. Note: This object is NOT a tensor.")
+
+    def _calculate_rank(self, arr):
+        """
+        Calculates the mathematical rank (number of indices) of the array
+        by measuring the depth of the nested lists.
+        """
+        if isinstance(arr, list):
+            return 1 + self._calculate_rank(arr[0])
+        return 0
+
+    # --- Core geometric operations for Connections ---
+    
+    def covariant_derivative(self, tensor_obj, verbose=False):
+        r"""
+        Computes the covariant derivative (\nabla_\mu) of a given tensor.
+        The derivative adds a new covariant index (lower 'l') at the beginning of the tensor.
+        Nabla_\mu T^{a}_{b} = \partial_\mu T^{a}_{b} + \Gamma^a_{\mu \sigma} T^\sigma_b - \Gamma^\sigma_{\mu b} T^a_\sigma
+        """
+        import symengine as se
+        
+        if verbose:
+            print(f"[{self.name}] Computing covariant derivative for tensor '{tensor_obj.name}'...")
+            
+        dims = self.dims
+        syms = self.syms
+        rank = len(tensor_obj.config)
+        T_data = tensor_obj.get_raw_data()
+        Gamma = self._data  # self is the connection, config 'ull': Gamma[up][down][down]
+        
+        # Helper to extract the tensor component safely regardless of rank
+        def get_T(indices):
+            val = T_data
+            for idx in indices:
+                val = val[idx]
+            return val
+
+        # The covariant derivative ADDS a new covariant index at the front.
+        # e.g., T^\alpha_\beta (config "ul") -> \nabla_\mu T^\alpha_\beta (config "lul")
+        new_config = 'l' + tensor_obj.config
+        
+        def build_cov_dir(current_indices):
+            # Base case: we have selected all coordinates for the new tensor
+            if len(current_indices) == rank + 1:
+                mu = current_indices[0]      # The derivative index (\nabla_\mu)
+                T_indices = current_indices[1:] # The original tensor indices
+                
+                # 1. Base term: Partial derivative \partial_\mu T^{...}
+                term = se.diff(get_T(T_indices), syms[mu])
+                
+                # 2. Correction terms: loop over each index of the original tensor
+                for p in range(rank):
+                    idx_type = tensor_obj.config[p]
+                    current_idx_val = T_indices[p]
+                    
+                    if idx_type == 'u':
+                        # Add connection term for contravariant index
+                        # + \sum_\sigma \Gamma^{current_idx_val}_{\mu \sigma} * T^{... \sigma ...}
+                        for sigma in range(dims):
+                            mod_indices = list(T_indices)
+                            mod_indices[p] = sigma
+                            term += Gamma[current_idx_val][mu][sigma] * get_T(mod_indices)
+                            
+                    elif idx_type == 'l':
+                        # Subtract connection term for covariant index
+                        # - \sum_\sigma \Gamma^{\sigma}_{\mu current_idx_val} * T^{... \sigma ...}
+                        for sigma in range(dims):
+                            mod_indices = list(T_indices)
+                            mod_indices[p] = sigma
+                            term -= Gamma[sigma][mu][current_idx_val] * get_T(mod_indices)
+                            
+                return term
+            
+            # Recursive case: dive deeper into the dimensions
+            else:
+                return [build_cov_dir(current_indices + [d]) for d in range(dims)]
+                
+        cov_data = build_cov_dir([])
+        
+        # Local import to avoid circular dependencies
+        from einsteinengine.symbolic.tensor import BaseRelativityTensor
+        
+        final_name = f"CovDeriv_{tensor_obj.name}"
+        return BaseRelativityTensor(cov_data, syms, config=new_config, name=final_name, verbose=verbose)
+
+

einsteinengine-0.5.0/einsteinengine/symbolic/core.py

@@ -0,0 +1,136 @@
+import symengine as se
+import sympy as sp
+import copy
+
+class BaseRelativityObject:
+    """
+    Absolute base class for any geometric object in EinsteinEngine.
+    Handles coordinate symbols, dimensions, and C++ SymEngine integration.
+    Does NOT assume tensor transformation laws.
+    """
+    def __init__(self, arr, syms, name="GeometricObject", verbose=False):
+        self.name = name
+        self.verbose = verbose
+        
+        # Coordinate Management (Our implicit Chart)
+        self.syms = [se.sympify(s) for s in syms]
+        self.dims = len(self.syms)
+        
+        # Convert mathematical arrays to high-performance C++ objects
+        self._data = self._symenginify_array(arr)
+        
+        if self.verbose:
+            print(f"[{self.name}] Instantiated in {self.dims}D spacetime.")
+
+    def get_raw_data(self):
+        """Returns the internal SymEngine matrix/array."""
+        return self._data
+
+    def _symenginify_array(self, arr):
+        """
+        Recursively converts Python lists/SymPy objects into SymEngine objects.
+        Works for 1D vectors, 2D matrices, or 4D Riemann structures.
+        """
+        if isinstance(arr, list):
+            return [self._symenginify_array(item) for item in arr]
+        else:
+            # Handles integers, floats, and SymPy expressions
+            return se.sympify(arr)
+
+    def _calculate_rank(self, arr):
+        """Calculates the mathematical rank dynamically."""
+        if isinstance(arr, list):
+            return 1 + self._calculate_rank(arr[0])
+        return 0
+
+    def _algebraic_contraction(self, idx1, idx2):
+        """
+        Hidden mathematical engine: Contracts two indices of an N-dimensional nested list.
+        Works recursively for any rank dynamically.
+        """
+        # Aseguramos que idx1 es el menor para no liarnos al reordenar
+        if idx1 > idx2:
+            idx1, idx2 = idx2, idx1
+            
+        rank = self._calculate_rank(self._data)
+        new_rank = rank - 2
+        
+        # Función auxiliar para extraer el valor en una coordenada N-dimensional
+        def get_element(indices):
+            val = self._data
+            for i in indices:
+                val = val[i]
+            return val
+            
+        # Función recursiva que construye la nueva matriz con N-2 dimensiones
+        def build_contracted(current_free_coords):
+            # Si ya tenemos suficientes coordenadas libres, sumamos el índice mudo (dummy)
+            if len(current_free_coords) == new_rank:
+                tmp_sum = se.sympify(0)
+                for dummy in range(self.dims):
+                    # Reconstruimos la coordenada original completa
+                    orig_coords = [0] * rank
+                    orig_coords[idx1] = dummy
+                    orig_coords[idx2] = dummy
+                    
+                    # Rellenamos el resto de huecos con las coordenadas libres
+                    free_ptr = 0
+                    for i in range(rank):
+                        if i != idx1 and i != idx2:
+                            orig_coords[i] = current_free_coords[free_ptr]
+                            free_ptr += 1
+                            
+                    tmp_sum += get_element(orig_coords)
+                return tmp_sum
+            else:
+                # Si faltan coordenadas, seguimos escarbando (recursión)
+                return [build_contracted(current_free_coords + [d]) for d in range(self.dims)]
+                
+        # Lanzamos la recursión desde cero
+        return build_contracted([])   
+    
+    def simplify(self, in_place=True):
+        """
+        Applies algebraic and trigonometric simplification to the object's data.
+        It uses SymPy's pattern recognition engine to collapse equations 
+        and then converts the data back to SymEngine for fast future computations.
+        
+        Args:
+            in_place (bool): If True, modifies the object's internal data. 
+                             If False, returns a new object with the simplified data, 
+                             leaving the original untouched.
+                             """
+        if self.verbose:
+            print(f"[{self.name}] Applying deep simplification... (This may take a while for large tensors)")
+
+        # Recursive helper function to dig into nested lists of any tensor rank
+        def _recursive_simplify(arr):
+            if isinstance(arr, list):
+                return [_recursive_simplify(item) for item in arr]
+            else:
+                # 1. Convert SymEngine object to pure SymPy (sp.sympify)
+                # 2. Apply deep algebraic/trigonometric simplification (sp.simplify)
+                # 3. Shield it back into C++ SymEngine for performance (se.sympify)
+                return se.sympify(sp.simplify(sp.sympify(arr)))
+
+        simplified_data = _recursive_simplify(self._data)
+
+        if in_place:
+            self._data = simplified_data
+            if self.verbose:
+                print(f"[{self.name}] Simplification complete.")
+                
+            # Return self to allow method chaining (e.g., tensor.simplify().get_raw_data())
+            return self
+        else:
+            # Creamos un clon exacto del objeto actual (sea Tensor, Conexión, etc.)
+            new_obj = copy.copy(self)
+            # Le inyectamos los datos limpios al clon
+            new_obj._data = simplified_data
+            if self.verbose:
+                print(f"[{self.name}] Created simplified copy.")
+            return new_obj
+
+    
+    
+    

einsteinengine-0.5.0/einsteinengine/symbolic/einstein_tensor.py

@@ -0,0 +1,57 @@
+import symengine as se
+from einsteinengine.symbolic.tensor import BaseRelativityTensor
+
+class EinsteinTensor(BaseRelativityTensor):
+    
+    @classmethod
+    def from_components(cls, metric, ricci_tensor, ricci_scalar, verbose=False):
+        """
+        Computes the Einstein Tensor (G_mu_nu) combining the geometric components:
+        G_mu_nu = R_mu_nu - (1/2) * R * g_mu_nu
+        """
+        if verbose:
+            print(f"Building Einstein Tensor for '{metric.name}'...")
+            
+        # 1. Extract pure C++ matrices from our objects
+        g_data = metric.get_raw_data()
+        R_mu_nu = ricci_tensor.get_raw_data()
+        R_scalar = ricci_scalar.get_raw_data()
+        
+        syms = metric.syms
+        dims = metric.dims
+        
+        # 2. Initialize a 2D matrix for G_mu_nu
+        G_tensor = [[se.sympify(0) for _ in range(dims)] for _ in range(dims)]
+        
+        # Exact symbolic fraction to avoid floating point precision issues
+        half = se.Rational(1, 2)
+        
+        # 3. Apply the fundamental formula cell by cell
+        for mu in range(dims):
+            for nu in range(dims):
+                G_tensor[mu][nu] = R_mu_nu[mu][nu] - half * R_scalar * g_data[mu][nu]
+                
+        # 4. Instantiate as a rank-2 covariant tensor (config="ll")
+        clean_name = metric.name.replace("Metric_", "")
+        return cls(G_tensor, syms, config="ll", name=f"Einstein_{clean_name}", verbose=verbose)
+    
+    @classmethod
+    def from_metric(cls, metric, verbose=False):
+        """
+        Convenience pipeline method: Computes the Einstein Tensor directly from a Metric.
+        """
+        if verbose:
+            print(f"--- Auto-generating Curvature Pipeline for '{metric.name}' ---")
+            
+        # Local imports
+        from einsteinengine.symbolic.riemann import RiemannCurvatureTensor
+        from einsteinengine.symbolic.ricci_tensor import RicciTensor
+        from einsteinengine.symbolic.ricci_scalar import RicciScalar
+
+        riemann = RiemannCurvatureTensor.from_metric(metric, verbose=verbose)
+        ricci_tensor = RicciTensor.from_riemann(riemann, verbose=verbose)
+        ricci_scalar = RicciScalar.from_ricci_tensor_and_metric(ricci_tensor, metric, verbose=verbose)
+
+        # Pass the calculated components to our main constructor
+        return cls.from_components(metric, ricci_tensor, ricci_scalar, verbose=verbose)
+

einsteinengine-0.5.0/einsteinengine/symbolic/energy_momentum.py

@@ -0,0 +1,45 @@
+import symengine as se
+from einsteinengine.symbolic.tensor import BaseRelativityTensor
+
+class EnergyMomentumTensor(BaseRelativityTensor):
+    
+    @classmethod
+    def from_perfect_fluid(cls, metric, density, pressure, four_velocity_cov, verbose=False):
+        r"""
+        Constructs the Energy-Momentum Tensor for a Perfect Fluid.
+        Formula: T_\mu\nu = (\rho + p) u_\mu u_\nu + p g_\mu\nu
+        
+        Args:
+            metric (MetricTensor): The metric tensor of the spacetime.
+            density (sp.Expr): The energy density (\rho).
+            pressure (sp.Expr): The isotropic pressure (p).
+            four_velocity_cov (list): The covariant four-velocity vector u_\mu (e.g., [-1, 0, 0, 0]).
+        """
+        if verbose:
+            print(f"Building Perfect Fluid Energy-Momentum Tensor for '{metric.name}'...")
+            
+        dims = metric.dims
+        syms = metric.syms
+        g_data = metric.get_raw_data()
+        
+        # 1. Symenginify physical parameters
+        rho = se.sympify(density)
+        p = se.sympify(pressure)
+        u_mu = [se.sympify(val) for val in four_velocity_cov]
+        
+        # 2. Initialize the 2D tensor T_\mu\nu
+        T_data = [[se.sympify(0) for _ in range(dims)] for _ in range(dims)]
+        
+        # Enthalpy factor: (\rho + p)
+        enthalpy = rho + p
+        
+        # 3. Apply the perfect fluid formula cell by cell
+        for mu in range(dims):
+            for nu in range(dims):
+                term1 = enthalpy * u_mu[mu] * u_mu[nu]
+                term2 = p * g_data[mu][nu]
+                T_data[mu][nu] = term1 + term2
+                
+        fluid_name = f"Fluid_{metric.name}"
+        # Returned as a doubly covariant tensor (config 'll')
+        return cls(T_data, syms, config="ll", name=fluid_name, verbose=verbose)

einsteinengine-0.5.0/einsteinengine/symbolic/geodesics.py

@@ -0,0 +1,96 @@
+import sympy as sp
+import symengine as se
+
+class Geodesics:
+    r"""
+    Computes the geodesic equations of motion for a given space-time.
+    d^2 x^\mu / d\tau^2 = - \Gamma^\mu_{\alpha\beta} (dx^\alpha / d\tau) (dx^\beta / d\tau)
+    """
+    
+    def __init__(self, christoffel, param_name="tau", verbose=False):
+        self.christoffel = christoffel
+        self.syms = christoffel.syms
+        self.dims = christoffel.dims
+        self.verbose = verbose
+        
+        # --- THEORETICAL VARIABLES (SymPy) ---
+        # Used ONLY for LaTeX display. SymEngine doesn't support abstract uncomputed Functions well.
+        self.tau_sp = sp.Symbol(param_name, real=True)
+        self.x_funcs_sp = [sp.Function(s.name)(self.tau_sp) for s in self.syms]
+        
+        # --- PERFORMANCE VARIABLES (SymEngine / C++) ---
+        # Algebraic velocities used for high-speed numerical simulations
+        self.v_syms_se = [se.Symbol(f"v_{s.name}") for s in self.syms]
+        
+        if self.verbose:
+            print(f"Initialized Geodesics equations generator. Affine parameter: {self.tau_sp}")
+
+    def get_equations(self, substitute_velocities=True, simplify=False):
+        """
+        Generates the right-hand side (accelerations) of the geodesic equations.
+        
+        Args:
+            substitute_velocities (bool): 
+                - If True (Default): C++ HIGH PERFORMANCE MODE. Returns algebraic system for SciPy.
+                - If False: PYTHON THEORETICAL MODE. Returns pure differential equations.
+            simplify (bool): If True, attempts to simplify the final expressions (can be slow).
+        """
+        if self.verbose:
+            print("Constructing the geodesic differential equations...")
+            
+        Gamma = self.christoffel.get_raw_data()
+        accelerations = []
+        
+        for mu in range(self.dims):
+            # Accumulator initialized purely in C++
+            accel_mu = se.sympify(0) if substitute_velocities else sp.sympify(0)
+            
+            for alpha in range(self.dims):
+                for beta in range(self.dims):
+                    # Fetch the Christoffel symbol component
+                    gamma_se = se.sympify(Gamma[mu][alpha][beta])
+                    
+                    if gamma_se == 0:
+                        continue
+                        
+                    if substitute_velocities:
+                        # 1. NUMERICAL MODE (SymEngine C++)
+                        # Pure, blazing fast algebra
+                        vel_alpha = self.v_syms_se[alpha]
+                        vel_beta = self.v_syms_se[beta]
+                        accel_mu += - gamma_se * vel_alpha * vel_beta
+                    else:
+                        # 2. THEORETICAL MODE (SymPy fallback)
+                        # We must cross the bridge to Python to use sp.Derivative and sp.Function
+                        gamma_sp = sp.sympify(gamma_se)
+                        subs_dict = {self.syms[i]: self.x_funcs_sp[i] for i in range(self.dims)}
+                        gamma_sp = gamma_sp.subs(subs_dict)
+                        
+                        vel_alpha = sp.Derivative(self.x_funcs_sp[alpha], self.tau_sp)
+                        vel_beta = sp.Derivative(self.x_funcs_sp[beta], self.tau_sp)
+                        accel_mu += - gamma_sp * vel_alpha * vel_beta
+            
+            # Performance delegation for simplification
+            if simplify:
+                if self.verbose: print(f"Simplifying equation for coordinate {self.syms[mu]}...")
+                # 1. C++ -> Python (sp.sympify)
+                cleaned_python_eq = sp.simplify(sp.sympify(accel_mu))
+                # 3. Python -> C++ (se.sympify)
+                accelerations.append(se.sympify(cleaned_python_eq))
+            else:
+                accelerations.append(accel_mu)
+            
+        return accelerations
+
+    def display_equations(self):
+        """
+        Helper method to render the theoretical differential equations in Jupyter Notebooks.
+        """
+        from IPython.display import display, Math
+        
+        # Force theoretical mode and skip simplification for instant rendering
+        eqs = self.get_equations(substitute_velocities=False, simplify=False)
+        for i, eq in enumerate(eqs):
+            coord = self.syms[i].name
+            latex_str = f"\\frac{{d^2 {coord}}}{{d\\tau^2}} = {sp.latex(eq)}"
+            display(Math(latex_str))

einsteinengine-0.5.0/einsteinengine/symbolic/metric.py

@@ -0,0 +1,60 @@
+import symengine as se
+import sympy as sp
+from einsteinengine.symbolic.tensor import BaseRelativityTensor
+
+class MetricTensor(BaseRelativityTensor):
+    r"""
+    Class representing the Metric Tensor ($g_{\mu\nu}$)
+    Inherits from BaseRelativityTensor
+    """
+    
+    def __init__(self, arr, syms, config="ll", name="MetricTensor", verbose=False):
+        # Call the parent constructor (tensor.py) to handle the heavy lifting
+        # setting up indices, names, and converting everything to SymEngine
+        super().__init__(arr, syms, config=config, name=name,verbose=verbose)
+        
+        if verbose:
+            print(f"[{self.name}] Métrica validada y lista para cálculos.")
+
+        if len(self._data) != len(self._data[0]):
+            raise ValueError("Metric must be a squared matrix")
+            
+        self.dims = len(syms)
+        
+        # Cache interna para la inversa, para no recalcularla múltiples veces
+        self._inverse_tensor = None
+
+    def inv(self):
+        """
+        Computes the inverse metric tensor (g^{mu nu}).
+        Uses a caching mechanism to avoid redundant calculations.
+        """
+        # If already computed, return it instantly
+        if self._inverse_tensor is not None:
+            return self._inverse_tensor
+
+        # If not, run the SymPy inversion pipeline
+        
+        sp_matrix = sp.Matrix(self._data)
+        dims = sp_matrix.shape[0]
+        
+        # Handle cases where SymEngine structures read the data as a flat 1D column
+        if sp_matrix.shape == (dims * dims, 1):
+            sp_matrix = sp_matrix.reshape(dims, dims)
+            
+        # Perform the algebraic inversion securely
+        sp_inv = sp_matrix.inv()
+        
+        # Safely parse the SymPy Matrix back into standard nested lists
+        inv_arr = sp_inv.tolist()
+        
+        # Store the instance before returning it
+        self._inverse_tensor = self.__class__(
+            inv_arr, 
+            self.syms, 
+            config="uu", 
+            name=f"{self.name}_inv", 
+            verbose=False
+        )
+        
+        return self._inverse_tensor