modusa 0.1.0__py3-none-any.whl

modusa/engines/plot_2dmatrix.py

@@ -0,0 +1,159 @@
+#!/usr/bin/env python3
+
+
+from modusa import excp
+from modusa.decorators import validate_args_type
+from modusa.engines.base import ModusaEngine
+from typing import Any
+import numpy as np
+import matplotlib.pyplot as plt
+from matplotlib.patches import Rectangle
+from matplotlib.ticker import MaxNLocator
+
+class Plot2DMatrixEngine(ModusaEngine):
+	"""
+
+	"""
+	
+	#--------Meta Information----------
+	name = "Plot 2D Matrix"
+	description = ""
+	author_name = "Ankit Anand"
+	author_email = "ankit0.anand0@gmail.com"
+	created_at = "2025-07-02"
+	#----------------------------------
+	
+	def __init__(self):
+		super().__init__()
+		
+	
+	@staticmethod
+	def compute_centered_extent(r: np.ndarray, c: np.ndarray, origin: str) -> list[float]:
+		"""
+		
+		"""
+		dc = np.diff(c).mean() if len(c) > 1 else 1
+		dr = np.diff(r).mean() if len(r) > 1 else 1
+		left   = c[0] - dc / 2
+		right  = c[-1] + dc / 2
+		bottom = r[0] - dr / 2
+		top    = r[-1] + dr / 2
+		return [left, right, top, bottom] if origin == "upper" else [left, right, bottom, top]
+	
+	
+	@validate_args_type()
+	def run(
+		self,
+		M: np.ndarray,
+		r: np.ndarray,
+		c: np.ndarray,
+		log_compression_factor: int | float | None,
+		ax: plt.Axes | None,
+		labels: tuple[str, str, str, str] | None,
+		zoom: tuple[float, float, float, float] | None,  # (r1, r2, c1, c2)
+		highlight: list[tuple[float, float, float, float]] | None,
+		cmap: str,
+		origin: str,  # or "lower"
+		show_colorbar: bool,
+		cax: plt.Axes | None,
+		show_grid: bool,
+		tick_mode: str,  # "center" or "edge"
+		n_ticks: tuple[int, int],
+		value_range: tuple[float, float] | None,
+	) -> plt.Figure:
+		pass
+		
+		# Validate the important args and get the signal that needs to be plotted
+		if M.ndim != 2:
+			raise excp.InputValueError(f"`M` must have 2 dimension not {M.ndim}")
+		if r.ndim != 1 and c.ndim != 1:
+			raise excp.InputValueError(f"`r` and `c` must have 2 dimension not r:{r.ndim}, c:{c.ndim}")
+			
+		if r.shape[0] != M.shape[0]:
+			raise excp.InputValueError(f"`r` must have shape as `M row` not {r.shape}")
+		if c.shape[0] != M.shape[1]:
+			raise excp.InputValueError(f"`c` must have shape as `M column` not {c.shape}")
+			
+		# Scale the signal if needed
+		if log_compression_factor is not None:
+			M = np.log1p(float(log_compression_factor) * M)
+		
+		# Create a figure
+		if ax is None:
+			fig, ax = plt.subplots(figsize=(15, 4))
+			created_fig = True
+		else:
+			fig = ax.get_figure()
+			created_fig = False
+		
+		# Plot the signal with right configurations
+		# Compute extent
+		extent = Plot2DMatrixEngine.compute_centered_extent(r, c, origin)
+		
+		# Plot image
+		im = ax.imshow(
+			M,
+			aspect="auto",
+			cmap=cmap,
+			origin=origin,
+			extent=extent,
+			vmin=value_range[0] if value_range else None,
+			vmax=value_range[1] if value_range else None,
+		)
+		
+		# Set the ticks and labels
+		if tick_mode == "center":
+			ax.yaxis.set_major_locator(MaxNLocator(nbins=n_ticks[0]))
+			ax.xaxis.set_major_locator(MaxNLocator(nbins=n_ticks[1]))  # limits ticks
+			
+		elif tick_mode == "edge":
+			dc = np.diff(c).mean() if len(c) > 1 else 1
+			dr = np.diff(r).mean() if len(r) > 1 else 1
+			ax.set_xticks(np.append(c, c[-1] + dc) - dc / 2)
+			ax.set_yticks(np.append(r, r[-1] + dr) - dr / 2)
+		
+		if labels is not None:
+			if len(labels) > 0:
+				ax.set_title(labels[0])
+			if len(labels) > 2:
+				ax.set_ylabel(labels[2])
+			if len(labels) > 3:
+				ax.set_xlabel(labels[3])
+		
+		# Zoom into a region
+		if zoom is not None:
+			r1, r2, c1, c2 = zoom
+			ax.set_xlim(min(c1, c2), max(c1, c2))
+			ax.set_ylim(
+				(min(r1, r2), max(r1, r2)) if origin == "lower" else (max(r1, r2), min(r1, r2))
+			)
+			
+		# Highlight a list of regions
+		if highlight is not None:
+			for r1, r2, c1, c2 in highlight:
+				row_min, row_max = min(r1, r2), max(r1, r2)
+				col_min, col_max = min(c1, c2), max(c1, c2)
+				width = col_max - col_min
+				height = row_max - row_min
+				ax.add_patch(Rectangle((col_min, row_min), width, height, color='red', alpha=0.2, zorder=10))
+		
+		# Show colorbar
+		if show_colorbar is not None:
+			cbar = fig.colorbar(im, ax=ax, cax=cax)
+			if len(labels) > 1:
+				cbar.set_label(labels[1])
+		
+		# Show grid
+		if show_grid:
+			ax.grid(True, color="gray", linestyle="--", linewidth=0.5) # TODO
+
+		# Show/Return the figure as per needed
+		if created_fig:
+			fig.tight_layout()
+			try:
+				get_ipython
+				plt.close(fig)
+				return fig
+			except NameError:
+				plt.show()
+				return fig

modusa/generators/__init__.py

@@ -0,0 +1,3 @@
+#!/usr/bin/env python3
+
+from .basic_waveform import BasicWaveformGenerator

modusa/generators/base.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+
+from modusa import excp
+from modusa.decorators import validate_args_type, immutable_property
+from modusa.signals import ModusaSignal
+from abc import ABC, abstractmethod
+from typing import Any
+
+class ModusaGenerator(ABC):
+	"""
+	Base class for any generator.
+	
+	Generates instance of different `ModusaSignal` subclass.
+	"""
+	
+	#--------Meta Information----------
+	name = ""
+	description = ""
+	author_name = "Ankit Anand"
+	author_email = "ankit0.anand0@gmail.com"
+	created_at = "2025-07-04"
+	#----------------------------------
+	
+	def __init__(self, signal_cls: Any):
+		
+		if not issubclass(signal_cls, ModusaSignal):
+			raise excp.InputValueError(f"`signal_cls` must be a subclass of ModusaSignal, got {signal_cls.__name__}")
+		if signal_cls not in self.allowed_output_signal_types:
+			raise excp.InputValueError(f"`signal_cls` must be a one of the allowed types {self.allowed_output_signal_types}, got {signal_cls.__name__}") 
+
+		self._signal_cls = signal_cls
+	
+	@immutable_property("Mutation not allowed.")
+	def signal_cls(self) -> Any:
+		return self._signal_cls
+	
+	@property
+	@abstractmethod
+	def allowed_output_signal_types(self) -> tuple[type, ...]:
+		return

modusa/generators/basic_waveform.py

@@ -0,0 +1,185 @@
+#!/usr/bin/env python3
+
+
+from modusa.decorators import validate_args_type
+from modusa.generators.base import ModusaGenerator
+from modusa.signals import UniformTimeDomainSignal, AudioSignal
+from typing import Any
+import numpy as np
+
+class BasicWaveformGenerator(ModusaGenerator):
+	"""
+
+	"""
+	
+	#--------Meta Information----------
+	name = ""
+	description = ""
+	author_name = "Ankit Anand"
+	author_email = "ankit0.anand0@gmail.com"
+	created_at = "2025-07-04"
+	#----------------------------------
+	
+	def __init__(self, signal_cls: Any | None = None):
+		if signal_cls is None:
+			signal_cls = self.allowed_output_signal_types[0] # Automatically select the first signal
+		super().__init__(signal_cls)
+	
+	
+	@property
+	def allowed_output_signal_types(self) -> tuple[type, ...]:
+		return (UniformTimeDomainSignal, AudioSignal)
+	
+	#----------------------------
+	# Generate functions
+	#----------------------------
+	
+	def generate_example(self):
+		"""
+		Generates an instance of `TimeDomainSignal` to test out the features quicky.
+		"""
+		
+		T = 0.01 # Time period
+		
+		t = np.arange(0, 10, T)
+		y = np.sin(2 * np.pi * 10 * t)
+		signal: UniformTimeDomainSignal | AudioSignal = self.signal_cls(y=y, t=t)
+		signal.set_units(t_unit="sec")
+		signal.set_name("Random")
+		signal.set_plot_labels(title=signal.name, y_label="Amplitude", t_label="Time")
+		
+		return signal
+	
+	def generate_random(self):
+		"""
+		Generates an instance of `TimeDomainSignal` with random initialisation.
+		Good for testing purposes.
+		"""
+		
+		T = np.random.random()
+		
+		t = np.arange(0, np.random.randint(10, 40), T)
+		y = np.random.random(size=t.shape[0])
+		signal: UniformTimeDomainSignal | AudioSignal = self.signal_cls(y=y, t=t)
+		signal.set_units(t_unit="sec")
+		signal.set_name("Random")
+		signal.set_plot_labels(title=signal.name, y_label="Amplitude", t_label="Time")
+		
+		return signal
+
+	@validate_args_type()
+	def generate_sinusoid(
+		self,
+		A: float | int = 1.0,
+		f: float | int = 10.0,
+		phi: float | int = 0.0,
+		duration: float | int = 1.0,
+		Ts: float | int = 0.01,
+	):
+		"""
+		Generates a sinusoidal `TimeDomainSignal` with specified frequency, duration, sampling period, and phase.
+		"""
+		
+		A, f, phi, duration, Ts = float(A), float(f), float(phi), float(duration), float(Ts)
+		
+		
+		t = np.arange(0, duration, Ts)
+		y = A * np.sin(2 * np.pi * f * t + phi)
+		
+		signal = self.signal_cls(y=y, t=t)
+		signal.set_name(name=f"Sinusoid: {f}Hz")
+		signal.set_plot_labels(
+			title=signal.name,
+			y_label="Amplitude",
+			t_label="Time"
+		)
+		
+		return signal
+
+
+	@validate_args_type()
+	def generate_square(
+		self,
+		A: float | int = 1.0,
+		f: float | int = 10.0,
+		phi: float | int = 0.0,
+		duration: float | int = 1.0,
+		Ts: float | int = 0.01,
+	):
+		"""
+		Generates a square wave
+		"""
+		
+		A, f, phi, duration, Ts = float(A), float(f), float(phi), float(duration), float(Ts)
+		
+		t = np.arange(0, duration, Ts)
+		y = A * np.sign(np.sin(2 * np.pi * f * t + phi))
+		
+		signal: UniformTimeDomainSignal | AudioSignal = self.signal_cls(y=y, t=t)
+		signal.set_units(t_unit="sec")
+		signal.set_name(name=f"Square: {f}Hz")
+		signal.set_plot_labels(
+			title=signal.name,
+			y_label="Amplitude",
+			t_label="Time"
+		)
+		
+		return signal
+
+	@validate_args_type()
+	def generate_sawtooth(
+		self,
+		A: float | int = 1.0,
+		f: float | int = 10.0,
+		phi: float | int = 0.0,
+		duration: float | int = 1.0,
+		Ts: float | int = 0.01,
+	):
+		"""
+		Generates a sawtooth wave.
+		"""
+		
+		A, f, phi, duration, Ts = float(A), float(f), float(phi), float(duration), float(Ts)
+		
+		t = np.arange(0, duration, Ts)
+		y = A * (2 * (t * f + phi) % 1 - 1)
+		
+		signal: UniformTimeDomainSignal | AudioSignal = self.signal_cls(y=y, t=t)
+		signal.set_units(t_unit="sec")
+		signal.set_name(name=f"Sawtooth: {f}Hz")
+		signal.set_plot_labels(
+			title=signal.name,
+			y_label="Amplitude",
+			t_label="Time"
+		)
+		
+		return signal
+
+	@validate_args_type()
+	def generate_triangle(
+		self,
+		A: float | int = 1.0,
+		f: float | int = 10.0,
+		phi: float | int = 0.0,
+		duration: float | int = 1.0,
+		Ts: float | int = 0.01,
+	):
+		"""
+		Generates a triangle wave
+		"""
+		
+		A, f, phi, duration, Ts = float(A), float(f), float(phi), float(duration), float(Ts)
+		
+		t = np.arange(0, duration, Ts)
+		signal = A * np.abs(2 * (t * f + phi) % 1 - 1)
+		
+		signal: UniformTimeDomainSignal | AudioSignal = self.signal_cls(y=y)
+		signal.set_units(t_unit="sec")
+		signal.set_name(name=f"Triangle: {f}Hz")
+		signal.set_plot_labels(
+			title=signal.name,
+			y_label="Amplitude",
+			t_label="Time"
+		)
+		
+		return signal

modusa/main.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+
+
+from line_profiler import LineProfiler
+from modusa.engines.plot_2dmatrix import Plot2DMatrixEngine
+import numpy as np
+
+M = np.abs(np.random.rand(1000, 1000))
+r = np.linspace(0, 1, M.shape[0])
+c = np.linspace(0, 1, M.shape[1])
+
+engine = Plot2DMatrixEngine()
+
+lp = LineProfiler()
+lp.add_function(engine.run.__wrapped__)
+
+lp_wrapper = lp(engine.run)
+lp_wrapper(
+	M, r, c,
+	log_compression_factor=None,
+	ax=None,
+	labels=("Title", "Colorbar", "Y", "X"),
+	zoom=None,
+	highlight=None,
+	cmap="gray_r",
+	origin="lower",
+	show_colorbar=True,
+	cax=None,
+	show_grid=False,
+	tick_mode="center",
+	n_ticks=(10, 10),
+	value_range=None
+)
+
+lp.print_stats()

modusa/plugins/__init__.py

@@ -0,0 +1,7 @@
+#!/usr/bin/env python3
+
+from .base import ModusaPlugin
+
+from .plot_1dsignal import Plot1DSignalPlugin
+from .plot_2dmatrix import Plot2DMatrixPlugin
+from .plot_time_domain_signal import PlotTimeDomainSignalPlugin

modusa/plugins/base.py

@@ -0,0 +1,100 @@
+#!/usr/bin/env python3
+
+from modusa.decorators import plugin_safety_check
+from abc import ABC, abstractmethod
+from typing import Any
+
+class ModusaPlugin(ABC):
+	"""
+	Base class for any Plugin that follows the modusa framework.
+	"""
+	
+	@property
+	@abstractmethod
+	def allowed_input_signal_types(self) -> tuple[type, ...]:
+		"""
+		Define the expected signal types for this plugin.
+		
+		Note
+		----
+		- Must be implemented by every `ModusaPlugin` subclass.
+		- Clearly states what signal types are accepted in `.apply()`.
+		- Return a tuple of accepted signal classes.
+		
+		Examples
+		--------
+		.. code-block:: python
+
+			# Single type
+			from modusa.signals import Signal1D
+			return (Signal1D, )
+		
+			# Multiple types
+			from modusa.signals import Signal1D, Signal2D
+			return (Signal1D, Signal2D)
+		"""
+		pass
+		
+	@property
+	@abstractmethod
+	def allowed_output_signal_types(self) -> tuple[type, ...]:
+		"""
+		Defines the allowed return types from the `.apply()` method.
+		
+		Note
+		----
+		- Must be implemented by every `ModusaPlugin` subclass.
+		- Clearly declares what return types are valid.
+		- Return a tuple of accepted types (usually signal classes).
+		
+		Examples
+		--------
+		.. code-block:: python
+
+			# Single type allowed
+			from modusa.signals import Signal1D
+			return (Signal1D, )
+		
+			# Multiple types allowed
+			from modusa.signals import Signal1D, Signal2D
+			return (Signal1D, Signal2D)
+		
+			# Return type can also be None (e.g., for plot-only plugins)
+			from modusa.signals import Signal1D, Signal2D
+			return (Signal1D, Signal2D, type(None))
+		"""
+		pass
+		
+	@plugin_safety_check()
+	@abstractmethod
+	def apply(self, signal: Any) -> Any:
+		"""
+		Defines the main processing logic of the plugin.
+		
+		Note
+		----
+		- Must be implemented by every `ModusaPlugin` subclass.
+		- It is highly advised to wrap it with `@plugin_safety_check()` to:
+			- Validate input and output types.
+			- Enforce plugin contracts for safe execution.
+		
+		Warning
+		-------
+		- You should not make this method as `classmethod` or `staticmethod`, this will break plugin safety check.
+		
+		Example
+		-------
+		.. code-block:: python
+			
+			@plugin_safety_check()
+			def apply(self, signal: "TimeDomainSignal") -> "TimeDomainSignal":
+				from modusa.engines import SomeEngine
+				new_signal: TimeDomainSignal = SomeEngine.run(signal)
+				
+				return new_signal
+		"""
+		pass
+		
+		
+	
+		

modusa/plugins/plot_1dsignal.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+
+
+from modusa.plugins.base import ModusaPlugin
+from modusa.decorators import immutable_property, validate_args_type, plugin_safety_check
+import matplotlib.pyplot as plt
+
+class Plot1DSignalPlugin(ModusaPlugin):
+	"""
+
+	"""
+	
+	#--------Meta Information----------
+	name = "Plot 1D Signal Plugin"
+	description = "A 1D signal plotter plugin with various features."
+	author_name = "Ankit Anand"
+	author_email = "ankit0.anand0@gmail.com"
+	created_at = "2025-07-02"
+	#----------------------------------
+	
+	def __init__(self):
+		super().__init__()
+	
+	@immutable_property(error_msg="Mutation not allowed.")
+	def allowed_input_signal_types(self) -> tuple[type, ...]:
+		from modusa.signals import Signal1D
+		return (Signal1D, )
+	
+	
+	@immutable_property(error_msg="Mutation not allowed.")
+	def allowed_output_signal_types(self) -> tuple[type, ...]:
+		return (plt.Figure, type(None)) # None is returned when we want to plot on a given axes, no figure is created in that case
+	
+	
+	@plugin_safety_check()
+	@validate_args_type()
+	def apply(
+		self,
+		signal: "Signal1D",
+		scale_y: tuple[float, float] | None = None,
+		scale_x: tuple[float, float] | None = None,
+		ax: plt.Axes | None = None,
+		color: str | None = "k",
+		marker: str | None = None,
+		linestyle: str | None = None,
+		stem: bool = False,
+		labels: tuple[str, str, str] | None = None,
+		legend_loc: str | None = None,
+		zoom: tuple[float, float] | None = None,
+		highlight: list[tuple[float, float], ...] | None = None,
+		show_grid: bool | None = False,
+	) -> plt.Figure:
+		
+		# Run the engine here
+		from modusa.engines import Plot1DSignalEngine
+		
+		fig: plt.Figure | None = Plot1DSignalEngine().run(y=signal.data, x=signal.x, scale_y=scale_y, scale_x=scale_x, ax=ax, color=color, marker=marker, linestyle=linestyle, stem=stem, labels=labels, legend_loc=legend_loc, zoom=zoom, highlight=highlight)
+		
+		return fig 

modusa/plugins/plot_2dmatrix.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+
+
+from modusa.plugins.base import ModusaPlugin
+from modusa.decorators import immutable_property, validate_args_type, plugin_safety_check
+import matplotlib.pyplot as plt
+
+class Plot2DMatrixPlugin(ModusaPlugin):
+	"""
+
+	"""
+	
+	#--------Meta Information----------
+	name = "Plot 2D Matrix Plugin"
+	description = "A 2D matrix plotter plugin with various features."
+	author_name = "Ankit Anand"
+	author_email = "ankit0.anand0@gmail.com"
+	created_at = "2025-07-02"
+	#----------------------------------
+	
+	def __init__(self):
+		super().__init__()
+		
+	@immutable_property(error_msg="Mutation not allowed.")
+	def allowed_input_signal_types(self) -> tuple[type, ...]:
+		from modusa.signals import Signal2D
+		return (Signal2D, )
+	
+	
+	@immutable_property(error_msg="Mutation not allowed.")
+	def allowed_output_signal_types(self) -> tuple[type, ...]:
+		return (plt.Figure, type(None)) # None is returned when we want to plot on a given axes, no figure is created in that case
+	
+	
+	@plugin_safety_check()
+	@validate_args_type()
+	def apply(self,
+		signal: "Signal2D",
+		log_compression_factor: int | float | None = None,
+		ax: plt.Axes | None = None,
+		labels: tuple[str, str, str, str] | None = None,
+		zoom: tuple[float, float, float, float] | None = None,  # (r1, r2, c1, c2)
+		highlight: list[tuple[float, float, float, float]] | None = None,
+		cmap: str = "gray_r",
+		origin: str = "upper",  # or "lower"
+		show_colorbar: bool = True,
+		cax: plt.Axes | None = None,
+		show_grid: bool = False,
+		tick_mode: str = "center",  # or "edge"
+		n_ticks: tuple[int, int] = (11, 21),
+		value_range: tuple[float, float] | None = None,
+		
+	) -> "Signal2D":
+		
+		# Run the engine here
+		from modusa.engines import Plot2DMatrixEngine
+		
+		fig: plt.Figure = Plot2DMatrixEngine().run(
+			M=signal.M,
+			r=signal.r,
+			c=signal.c,
+			log_compression_factor=log_compression_factor,
+			ax=ax,
+			labels=signal.labels,
+			zoom=zoom,
+			highlight=highlight,
+			cmap=cmap,
+			origin=origin,
+			show_colorbar=show_colorbar,
+			cax=cax,
+			show_grid=show_grid,
+			tick_mode=tick_mode,
+			n_ticks=n_ticks,
+			value_range=value_range)
+		
+		return fig