SignalForge 0.0.2__tar.gz → 1.0.0__tar.gz

signalforge-1.0.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: SignalForge
+Version: 1.0.0
+Summary: A comprehensive Python package for generating and analyzing non-Gaussian and non-stationary signals.
+Home-page: https://github.com/GiulioCurti/SignalForge
+Author: Giulio Curti
+Author-email: Giulio Curti <giulio.curti@dottorandi.unipg.it>
+License: MIT
+Project-URL: Homepage, https://github.com/GiulioCurti/SignalForge
+Project-URL: Documentation, https://signalforge.readthedocs.io/
+Project-URL: Repository, https://github.com/GiulioCurti/SignalForge.git
+Project-URL: Bug-Tracker, https://github.com/GiulioCurti/SignalForge/issues
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.0
+Requires-Dist: scipy
+Requires-Dist: matplotlib>=3.10
+Requires-Dist: tqdm
+Requires-Dist: PyWavelets
+Requires-Dist: pyNNST
+Requires-Dist: statsmodels
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+
+[![SignalForge Testing](https://github.com/GiulioCurti/SignalForge/actions/workflows/python-app.yml/badge.svg)](https://github.com/GiulioCurti/SignalForge/actions/workflows/python-app.yml)
+[![Documentation Status](https://app.readthedocs.org/projects/signalforge/badge/?version=latest)](https://signalforge.readthedocs.io/en/latest/)
+
+SignalForge
+-----------
+
+SignalForge is an open-source Python package that provides a comprehensive set of tools for analyzing and generating non-Gaussian, non-stationary signals in engineering applications. While traditional signal processing methods often rely on assumptions of Gaussianity and stationarity, real-world signals—especially those found in mechanical systems—frequently deviate from these idealized models. SignalForge bridges this gap by offering advanced, yet user-friendly tools to simulate, inspect, and manipulate signals with complex statistical properties. Whether you're designing loads for testing, exploring time-varying behavior, or developing new algorithms, SignalForge enables you to work with signals that better reflect real operating conditions. Built with extensibility and clarity in mind, the package is suitable for researchers, practitioners, and students working across mechanical engineering, signal processing, and beyond.
+
+See the [documentation](<https://signalforge.readthedocs.io/en/latest/>) for a complete overview of the implemented methods for analisys and signal generation.
+
+Installing SignalForge
+------------------------------------------------------------
+The package is published in PiPy. To install it:
+```bash
+pip install signalforge
+```
+or you can clone it from GitHub
+```bash
+git clone https://github.com/GiulioCurti/SignalForge.git
+```
+and locally install it from inside the folder SignalForge
+```bash
+pip install -e .
+```
+
+Example code on how to generate a Stationary Gaussian Signal
+------------------------------------------------------------
+
+Stationary Gaussian signals can be easily generated via the specific class StationaryGaussian. Its usage is briefly shown in the following example code:
+
+```python
+from SignalForge import StationaryGaussian
+
+fpsd = [10,20]  # Frequency vector [Hz]
+psd = [1,1]     # Power density vecrtor [(m/s^2)^2/Hz]
+fs = 200        # Sampling frequency [Hz]
+T = 200         # Time duration [s]
+gauss_signal = StationaryGaussian(
+    fpsd=fpsd, 
+    psd=psd, 
+    fs=fs, 
+    T = T, 
+    name = 'Stationary Gaussian', 
+    unit='$m/s^2$'
+    ) # StationaryGaussian class initialization
+print(gauss_signal)
+gauss_signal.plot()           # Plotting Timehistory
+gauss_signal.plot_psd()       # Plotting Power spectral density 
+```
+Implemented non-linear transformartion methods to add non-gaussianity are the following:
+
+-	Hermite-Winterstein ('winter')
+-	Cubic polynomial ('cubic')
+-	Hyperbolic transform – Zheng (‘zheng’)
+-	Sarkani ('sarkani') 
+-	Improved nonlinear transform ('zmnl')
+-	Steinwolf ('steinwolf')
+-	Smallwoood Poisson shots ('smallwood')
+-	Van Baren ('vanbaren')  
+
+Example code on how to generate a Stationary Non Gaussian Signal
+------------------------------------------------------------
+
+Stationary non Gaussian signals can be easily generated via the specific class StationaryNonGaussian. Its usage is briefly shown in the following example code:
+
+```python
+from SignalForge import StationaryNonGaussian
+
+fpsd = [10,20]  # Frequency vector [Hz]
+psd = [1,1]     # Power density vecrtor [(m/s^2)^2/Hz]
+fs = 200        # Sampling frequency [Hz]
+T = 200         # Time duration [s]
+input_kurtosis = 6
+nongauss_signal = StationaryNonGaussian(
+    fpsd = fpsd, 
+    psd = psd,
+    T = T, 
+    kurtosis=input_kurtosis,
+    fs = fs, 
+    method='zmnl', 
+    name = 'Stationary NonGaussian', 
+    unit='$m/s^2$'
+    ) # StationaryNonGaussian class initalization
+print(nongauss_signal)
+nongauss_signal.plot()      # Plotting Timehistory
+nongauss_signal.plot_psd()  # Plotting Power spectral density 
+nongauss_signal.plot_fft()  # Plotting Fourier Transform
+```
+
+Example code on how to generate a Non Stationary Non Gaussian Signal
+------------------------------------------------------------
+
+Non stationary non Gaussian signals can be easily generated via the specific class NonStationaryGaussian. Its usage is briefly shown in the following example code:
+
+```python
+from SignalForge import NonStationaryNonGaussian
+
+fpsd = [10,20]  # Frequency vector [Hz]
+psd = [1,1]     # Power density vecrtor [(m/s^2)^2/Hz]
+fs = 200        # Sampling frequency [Hz]
+T = 200         # Time duration [s]
+params = {'input_kurtosis': 10}
+nonstat_signal = NonStationaryNonGaussian(
+    fpsd = fpsd, 
+    psd = psd, 
+    T = T,
+    params = params,
+    fs = fs, 
+    method='trapp_am', 
+    name = 'NonStationary NonGaussian', 
+    unit='$m/s^2$'
+    ) # NonStationaryNonGaussian class initalization
+print(nonstat_signal)
+nonstat_signal.plot()      # Plotting Timehistory
+nonstat_signal.plot_psd()  # Plotting Timehistory
+nonstat_signal.plot_sftf()  # Plotting Short Time Fourier Transform
+```
+Implemented transformartion methods to build non-gaussianity signals are the following:
+
+-	Beta amplitude modulation ('beta_am')
+-	Gaussian amplitude modulation ('trapp_am')
+-	Rayleigh amplitude modulation ('ray_am') 
+-	Frequency modulation via STFT ('fm')
+
+
+

{signalforge-0.0.2 → signalforge-1.0.0}/README.md

@@ -14,6 +14,14 @@ The package is published in PiPy. To install it:
 ```bash
 pip install signalforge
 ```
+or you can clone it from GitHub
+```bash
+git clone https://github.com/GiulioCurti/SignalForge.git
+```
+and locally install it from inside the folder SignalForge
+```bash
+pip install -e .
+```
 
 Example code on how to generate a Stationary Gaussian Signal
 ------------------------------------------------------------

{signalforge-0.0.2 → signalforge-1.0.0}/SignalForge/__init__.py

@@ -1,4 +1,4 @@
-__version__ = '0.0.2'
+__version__ = '1.0.0'
 from .single_chan_signal import *
 from .stationary_gaussian import *
 from .stationary_nongaussian import *

{signalforge-0.0.2 → signalforge-1.0.0}/SignalForge/nonstationary_nongaussian.py

@@ -1,7 +1,4 @@
-import numpy as np
-import scipy as sp
 import matplotlib.pyplot as plt
-from tqdm import tqdm
 
 from .utils import *
 from .single_chan_signal import SingleChanSignal
@@ -267,12 +264,48 @@ def get_trapp_amplitude_modulation(
     A. Trapp, M. J. Makua, e P. Wolfsteiner, «Fatigue assessment of amplitude-modulated non-stationary random vibration loading», Procedia Struct. Integr., vol. 17, pp. 379–386, 2019, doi: 10.1016/j.prostr.2019.08.050.
     """
     def get_trapp_carrier(p, delta_m, gaussian_carier): 
-        """Generate amplitude modulation carrier based on power-law transformation."""  
+        """
+        Generate amplitude modulation carrier based on power-law transformation.
+
+        Parameters
+        ----------
+        p : float
+            Exponent for the power-law transformation.
+        delta_m : float
+            Offset for the amplitude modulation.
+        gaussian_carier : np.ndarray
+            The Gaussian carrier signal.
+
+        Returns
+        -------
+        np.ndarray
+            The transformed Rayleigh carrier signal.
+        """  
         ray_carrier = np.abs(gaussian_carier)**p+delta_m
         return ray_carrier
     
     def trapp_am_opt_fun(params, gauss_carrier, input_kurtosis):
-        """Optimization objective: match output signal kurtosis and reduce skew."""
+        """
+        Optimization objective function for Trapp amplitude modulation.
+
+        This function calculates the absolute difference between the transformed
+        signal's kurtosis and skewness and the target values.
+
+        Parameters
+        ----------
+        params : list
+            Parameters for the `get_trapp_carrier` function.
+        gauss_carrier : np.ndarray
+            The Gaussian carrier signal.
+        input_kurtosis : float
+            The target kurtosis.
+
+        Returns
+        -------
+        float
+            The absolute difference between the transformed signal's kurtosis and skewness
+            and the target values.
+        """
         carrier = get_trapp_carrier(*params, gaussian_carier=gauss_carrier)
         nonstat_sign = _add_am_carrier(gauss_signal, carrier)
         transformed_kurtosis = sp.stats.kurtosis(nonstat_sign) + 3
@@ -386,19 +419,49 @@ class NonStationaryNonGaussian(SingleChanSignal):
             PSD interpolation method: 'lin' or 'log'. Default is 'lin'.
     """
     def __init__(
-        self, 
-        fpsd:np.ndarray, 
-        psd:np.ndarray, 
-        T:float, 
+        self,
+        fpsd:np.ndarray,
+        psd:np.ndarray,
+        T:float,
         fs:float = None,
-        dfpsd:float = 0.5, 
-        method:str = 'beta_am', 
-        params = None, 
-        name:str="", 
-        var:str='x', 
-        unit:str="$m/s^2$", 
-        seed:int=None, 
-        interp:str ='lin'):        
+        dfpsd:float = 0.5,
+        method:str = 'beta_am',
+        params = None,
+        name:str="",
+        var:str='x',
+        unit:str="$m/s^2$",
+        seed:int=None,
+        interp:str ='lin'):
+        """
+        Initializes a NonStationaryNonGaussian signal generator.
+
+        Parameters
+        ----------
+            fpsd : np.ndarray
+                Frequency vector for the input PSD.
+            psd : np.ndarray
+                Power spectral density values.
+            T : float
+                Total duration of the signal [s].
+            fs : float, optional
+                Wanted sampling frequency. If None -> 2*fpsd[-1].
+            dfpsd : float, optional
+                Frequency resolution [Hz]. Default is 0.5.
+            method : str, optional
+                Modulation method: 'beta_am', 'ray_am', 'trapp_am', or 'fm'. Default is 'beta_am'.
+            params : dict, optional
+                Dictionary of parameters for the modulation method.
+            name : str, optional
+                Name of the signal.
+            var : str, optional
+                Variable symbol, e.g., 'x'.
+            unit : str, optional
+                Signal unit. Default is '$m/s^2$'.
+            seed : int, optional
+                Random seed for reproducibility.
+            interp : str, optional
+                PSD interpolation method: 'lin' or 'log'. Default is 'lin'.
+        """        
         
         method = method.lower()
         interp = interp.lower()