modusa 0.4.29__py3-none-any.whl → 0.4.31__py3-none-any.whl

modusa/generators/audio_waveforms.py

@@ -1,236 +0,0 @@
-#!/usr/bin/env python3
-
-
-from modusa import excp
-from modusa.decorators import validate_args_type
-from modusa.generators.base import ModusaGenerator
-from modusa.models.audio_signal import AudioSignal
-import numpy as np
-
-class AudioWaveformGenerator(ModusaGenerator):
-	"""
-	Generates different kinds of audio waveforms particulary helpful
-	in teaching signal processing concepts and testing out newly
-	created tools.
-	"""
-	
-	#--------Meta Information----------
-	_name = "Audio Waveform Generator"
-	_description = "Generates different kind of audio waveforms."
-	_author_name = "Ankit Anand"
-	_author_email = "ankit0.anand0@gmail.com"
-	_created_at = "2025-07-07"
-	#----------------------------------
-	
-	@staticmethod
-	def generate_example() -> "AudioSignal":
-		"""
-		Generates a simple sine wave audio signal as an example.
-	
-		Returns
-		-------
-		AudioSignal
-			A 600 Hz sine wave lasting 2 seconds, sampled at 10,000 Hz.
-		"""
-		
-		sr = 10000 # Hz
-		duration = 2 # sec
-		freq = 600 # Hz
-		
-		t = np.arange(0, duration, 1 / sr)
-		y = np.sin(2 * np.pi * freq * t)
-		
-		signal = AudioSignal(y=y, sr=sr, title="Example")  # assuming AudioSignal accepts y and t
-		
-		return signal
-	
-	
-	@staticmethod
-	def generate_random(duration: float = 1.0, sr: int = 10000) -> "AudioSignal":
-		"""
-		Generates a random audio signal of given duration and sample rate.
-	
-		Parameters
-		----------
-		duration : float, optional
-			Duration of the signal in seconds (default is 1.0).
-		sr : int, optional
-			Sampling rate in Hz (default is 10,000).
-	
-		Returns
-		-------
-		AudioSignal
-			A randomly generated signal of the specified duration and sample rate.
-		"""
-		num_samples = int(duration * sr)
-		t = np.linspace(0, duration, num=num_samples, endpoint=False)
-		y = np.random.uniform(low=-1.0, high=1.0, size=num_samples)  # use uniform [-1, 1] for audio-like signal
-		
-		signal = AudioSignal(y=y, t=t, title="Random")
-		
-		return signal
-	
-	@staticmethod
-	@validate_args_type()
-	def generate_sinusoid(
-		A: float | int = 1.0,
-		f: float | int = 10.0,
-		phi: float | int = 0.0,
-		duration: float | int = 1.0,
-		sr: int = 1000,
-	) -> "AudioSignal":
-		"""
-		Generates a sinusoid audio signal with specified
-		amplitude, frequency, phase, duration, and sample rate.
-	
-		Parameters
-		----------
-		A : float
-			Amplitude of the sinusoid (default: 1.0)
-		f : float
-			Frequency in Hz (default: 10.0)
-		phi : float
-			Phase in radians (default: 0.0)
-		duration : float
-			Duration of the signal in seconds (default: 1.0)
-		sr : int
-			Sampling rate in Hz (default: 1000)
-	
-		Returns
-		-------
-		AudioSignal
-			A sinusoidal signal with the given parameters.
-		"""
-		A, f, phi, duration, sr = float(A), float(f), float(phi), float(duration), int(sr)
-		
-		t = np.arange(0, duration, 1 / sr)
-		y = A * np.sin(2 * np.pi * f * t + phi)
-		
-		signal = AudioSignal(y=y, sr=sr, title=f"Sinusoid ({f} Hz)")
-		
-		return signal
-	
-	@staticmethod
-	@validate_args_type()
-	def generate_square(
-		A: float | int = 1.0,
-		f: float | int = 10.0,
-		phi: float | int = 0.0,
-		duration: float | int = 1.0,
-		sr: int = 1000,
-	) -> "AudioSignal":
-		"""
-		Generates a square wave audio signal with specified
-		amplitude, frequency, phase, duration, and sample rate.
-	
-		Parameters
-		----------
-		A : float
-			Amplitude of the square wave (default: 1.0)
-		f : float
-			Frequency in Hz (default: 10.0)
-		phi : float
-			Phase in radians (default: 0.0)
-		duration : float
-			Duration of the signal in seconds (default: 1.0)
-		sr : int
-			Sampling rate in Hz (default: 1000)
-	
-		Returns
-		-------
-		AudioSignal
-			A square wave signal of the specified parameters.
-		"""
-		A, f, phi, duration, sr = float(A), float(f), float(phi), float(duration), int(sr)
-		t = np.arange(0, duration, 1 / sr)
-		
-		y = A * np.sign(np.sin(2 * np.pi * f * t + phi))
-		
-		signal = AudioSignal(y=y, sr=sr, title=f"Square ({f} Hz)")
-		
-		return signal
-	
-	
-	@staticmethod
-	@validate_args_type()
-	def generate_sawtooth(
-		A: float | int = 1.0,
-		f: float | int = 10.0,
-		phi: float | int = 0.0,
-		duration: float | int = 1.0,
-		sr: int = 1000,
-	) -> "AudioSignal":
-		"""
-		Generates a sawtooth wave AudioSignal with specified amplitude, frequency, phase, duration, and sample rate.
-	
-		Parameters
-		----------
-		A : float
-			Amplitude of the sawtooth wave (default: 1.0)
-		f : float
-			Frequency in Hz (default: 10.0)
-		phi : float
-			Phase in radians (default: 0.0)
-		duration : float
-			Duration of the signal in seconds (default: 1.0)
-		sr : int
-			Sampling rate in Hz (default: 1000)
-	
-		Returns
-		-------
-		AudioSignal
-			A sawtooth wave signal of the specified parameters.
-		"""
-		A, f, phi, duration, sr = float(A), float(f), float(phi), float(duration), int(sr)
-		t = np.arange(0, duration, 1 / sr)
-		
-		# Convert phase from radians to fractional cycle offset
-		phase_offset = phi / (2 * np.pi)
-		y = A * (2 * ((f * t + phase_offset) % 1) - 1)
-		
-		signal = AudioSignal(y=y, sr=sr, title=f"Sawtooth ({f} Hz)")
-		return signal
-	
-	
-	@staticmethod
-	@validate_args_type()
-	def generate_triangle(
-		A: float | int = 1.0,
-		f: float | int = 10.0,
-		phi: float | int = 0.0,
-		duration: float | int = 1.0,
-		sr: int = 1000,
-	) -> "AudioSignal":
-		"""
-		Generates a triangle wave AudioSignal with specified
-		amplitude, frequency, phase, duration, and sample rate.
-	
-		Parameters
-		----------
-		A : float
-			Amplitude of the triangle wave (default: 1.0)
-		f : float
-			Frequency in Hz (default: 10.0)
-		phi : float
-			Phase in radians (default: 0.0)
-		duration : float
-			Duration of the signal in seconds (default: 1.0)
-		sr : int
-			Sampling rate in Hz (default: 1000)
-	
-		Returns
-		-------
-		AudioSignal
-			A triangle wave signal of the specified parameters.
-		"""
-		A, f, phi, duration, sr = float(A), float(f), float(phi), float(duration), int(sr)
-		t = np.arange(0, duration, 1 / sr)
-		phase_offset = phi / (2 * np.pi)  # Convert radians to cycle offset
-		
-		# Triangle wave formula: 2 * abs(2 * frac(x) - 1) - 1 scaled to amplitude
-		y = A * (2 * np.abs(2 * ((f * t + phase_offset) % 1) - 1) - 1)
-		
-		signal = AudioSignal(y=y, sr=sr, title=f"Triangle ({f} Hz)")
-		
-		return signal
-	

modusa/generators/base.py

@@ -1,29 +0,0 @@
-#!/usr/bin/env python3
-
-from modusa import excp
-from modusa.decorators import validate_args_type, immutable_property
-from modusa.models.base import ModusaSignal
-from abc import ABC, abstractmethod
-from typing import Any
-
-class ModusaGenerator(ABC):
-	"""
-	Base class for any type of signal generators for modusa framework.
-	
-	Note
-	----
-	- This class is intended to be subclassed by any Generator related tools built for the modusa framework.
-	- In order to create a generator tool, you can use modusa-dev CLI to generate an generator template.
-	- It is recommended to treat subclasses of ModusaGenerator as namespaces and define @staticmethods with control parameters, rather than using instance-level __init__ methods.
-	
-	
-	"""
-	
-	#--------Meta Information----------
-	_name = ""
-	_description = ""
-	_author_name = "Ankit Anand"
-	_author_email = "ankit0.anand0@gmail.com"
-	_created_at = "2025-07-04"
-	#----------------------------------
-	

modusa/generators/ftds.py

@@ -1,298 +0,0 @@
-#!/usr/bin/env python3
-
-
-from modusa import excp
-from modusa.decorators import validate_args_type
-from .base import ModusaGenerator
-from modusa.models.data import Data
-from modusa.models.s_ax import SAx
-from modusa.models.t_ax import TAx
-from modusa.models.ftds import FTDS
-import numpy as np
-
-class FTDSGen(ModusaGenerator):
-	"""
-	Provides user friendly APIs to generate instances of different 
-	`FTDS` instances.
-	"""
-	
-	#--------Meta Information----------
-	_name = ""
-	_description = ""
-	_author_name = "Ankit Anand"
-	_author_email = "ankit0.anand0@gmail.com"
-	_created_at = "2025-07-27"
-	#----------------------------------
-	
-	@staticmethod
-	def from_array(
-		M: np.ndarray | list | float | int | np.generic,
-		f: np.ndarray | list | float | int | np.generic | None = None,
-		sr: int | float = 1.0,
-		t0: int | float = 0.0,
-		M_label: str = "M",
-		f_label: str = "Feature",
-		t_label: str = "Time (sec)",
-		title: str = "Feature Time Domain Signal"
-	) -> FTDS:
-		"""
-		Create `FDTS` instance from basic data structures.
-
-		.. code-block:: python
-
-			import modusa as ms
-			M = ms.ftds.from_array([1, 2, 3])
-			print(M)
-			M.print_info()
-		
-		Parameters
-		----------
-		M: np.ndarray | list | float | int | np.generic
-			- Data values.
-		f: np.ndarray | list | float | int | np.generic | None
-			- y axis values.
-			- Default: None → Creates an integer indexing.
-		sr: int | float
-			- Sampling rate / Frame rate.
-			- Default: 1.0
-		t0: int | float
-			- Start timestamp.
-			- Default: 0.0
-		M_label: str
-			- Label for the data.
-			- Default: "M"
-		f_label: str
-			- Feature label for the signal.
-			- Default: "Feature"
-		t_label: str
-			- Time label for the signal.
-			- Default: "Time (sec)"
-		title: str
-			- Title for the signal.
-			- Default: "Feature Time Domain Signal"
-		Returns
-		-------
-		FTDS
-			An instance of FTDS.
-		"""
-		assert isinstance(M, (np.ndarray, list, float, int, np.generic))
-		assert isinstance(f, (np.ndarray, list, float, int, np.generic)) or f is None
-		assert isinstance(sr, (int, float)) and isinstance(t0, (int, float))
-		assert isinstance(M_label, str) and isinstance(f_label, str) and isinstance(t_label, str) and isinstance(title, str)
-		
-		if isinstance(M, (float, int, np.generic)): M = [[M]] # Convert to list of 1 element
-		if isinstance(f, (float, int, np.generic)): f = [f] # Convert to list of 1 element
-		
-		M = np.asarray(M)
-		assert M.ndim == 2
-		
-		if f is None: f = np.arange(M.shape[0])
-		else: f = np.asarray(f)
-		assert f.ndim == 1
-		assert f.shape[0] == M.shape[0], "Shape mismatch"
-		
-		sr = float(sr)
-		t0 = float(t0)
-		
-		M = Data(values=M, label=M_label)
-		f = SAx(values=f, label=f_label)
-		t = TAx(n_points=M.shape[1], sr=sr, t0=t0, label=t_label)
-		
-		return FTDS(M=M, f=f, t=t, title=title)
-	
-	@classmethod
-	def zeros(cls, shape, f=None, sr=1.0, t0=0.0) -> FTDS:
-		"""
-		Create `FTDS` instance with all zeros.
-
-		.. code-block:: python
-
-			import modusa as ms
-			M = ms.ftds.zeros((10, 5))
-			print(M)
-			M.print_info()
-		
-		Parameters
-		----------
-		shape: tuple[int, int]
-			- Shape of the signal with zeros.
-			- Must be 1 dimensional
-			- E.g. (10, 5)
-		Returns
-		-------
-		FTDS
-			An instance of FTDS.
-		"""
-		assert isinstance(shape, tuple)
-		M = np.zeros(shape)
-		
-		return cls.from_array(M=M, f=f, sr=sr, t0=t0, title="Zeros")
-	
-	@classmethod
-	def zeros_like(cls, signal: FTDS) -> FTDS:
-		"""
-		Create `FTDS` instance similar to `signal`
-		but with all entries being zeros.
-
-		.. code-block:: python
-
-			import modusa as ms
-			signal = ms.ftds.from_array([[1, 2, 3], [4, 5, 6]])
-			M = ms.ftds.zeros_like(signal)
-			print(M)
-			M.print_info()
-		
-		Parameters
-		----------
-		signal: FTDS
-			- Reference signal to create zeros like that.
-		Returns
-		-------
-		FTDS
-			An instance of FTDS.
-		"""
-		
-		assert signal.__class__ in [FTDS]
-		
-		M = np.zeros(signal.shape)
-		f = signal._f
-		t = signal._t
-		
-		M_label = signal._M_label
-		f_label = signal._f_label
-		t_label = signal._t_label
-		title = signal._title
-		
-		return cls.from_array(M=M, f=f, t=t, M_label=M_label, f_label=f_label, t_label=t_label, title=title)
-	
-	
-	@classmethod
-	def ones(cls, shape: tuple[int, int]) -> FTDS:
-		"""
-		Create `FTDS` instance with all ones.
-
-		.. code-block:: python
-
-			import modusa as ms
-			M = ms.ftds.ones((10, 5))
-			print(M)
-			M.print_info()
-		
-		Parameters
-		----------
-		shape: tuple[int, int]
-			- Shape of the signal with ones.
-			- Must be 1 dimensional
-			- E.g. (10, 5)
-		Returns
-		-------
-		FTDS
-			An instance of FTDS.
-		"""
-		assert isinstance(shape, tuple)
-		M = np.ones(shape)
-		
-		return cls.from_array(M=M, title="Ones")
-	
-	@classmethod
-	def ones_like(cls, signal: FTDS) -> FTDS:
-		"""
-		Create `FTDS` instance similar to `signal`
-		but with all entries being ones.
-
-		.. code-block:: python
-
-			import modusa as ms
-			signal = ms.ftds.from_array([[1, 2, 3], [4, 5, 6]])
-			M = ms.ftds.ones_like(signal)
-			print(M)
-			M.print_info()
-		
-		Parameters
-		----------
-		signal: FTDS
-			- Reference signal to create ones like that.
-		Returns
-		-------
-		FTDS
-			An instance of FTDS.
-		"""
-		
-		assert signal.__class__ in [FTDS]
-		
-		M = np.ones(signal.shape)
-		f = signal._f
-		t = signal._t
-		
-		M_label = signal._M_label
-		f_label = signal._f_label
-		t_label = signal._t_label
-		title = signal._title
-		
-		return cls.from_array(M=M, f=f, t=t, M_label=M_label, f_label=f_label, t_label=t_label, title=title)
-	
-	@classmethod
-	def random(cls, shape: tuple[int, int]) -> FTDS:
-		"""
-		Create `FTDS` instance with random entries.
-
-		.. code-block:: python
-
-			import modusa as ms
-			M = ms.ftds.random((10, 5))
-			print(M)
-			M.print_info()
-		
-		Parameters
-		----------
-		shape: tuple[int, int]
-			- Shape of the signal with random values.
-			- Must be 1 dimensional
-			- E.g. (10, 5)
-		Returns
-		-------
-		FTDS
-			An instance of FTDS.
-		"""
-		assert isinstance(shape, tuple)
-		M = np.random.random(shape)
-		
-		return cls.from_array(M=M, title="Random")
-	
-	@classmethod
-	def random_like(cls, signal: FTDS) -> FTDS:
-		"""
-		Create `FTDS` instance similar to `signal`
-		but with random entries.
-
-		.. code-block:: python
-
-			import modusa as ms
-			signal = ms.ftds.from_array([[1, 2, 3], [4, 5, 6]])
-			M = ms.ftds.random_like(signal)
-			print(M)
-			M.print_info()
-		
-		Parameters
-		----------
-		signal: FTDS
-			- Reference signal.
-		Returns
-		-------
-		FTDS
-			An instance of FTDS with random values.
-		"""
-		
-		assert signal.__class__ in [FTDS]
-		
-		M = np.random.random(signal.shape)
-		f = signal._f
-		t = signal._t
-		
-		M_label = signal._M_label
-		f_label = signal._f_label
-		t_label = signal._t_label
-		title = signal._title
-		
-		return cls.from_array(M=M, f=f, t=t, M_label=M_label, f_label=f_label, t_label=t_label, title=title)
-