Documentation home / Native modules / gs_signal
gs_signal: Digital Signal Processing API
Complete source-grounded API reference for greenServeFE gs_signal: sampled waveform generation, measurements, normalization, moving averages, convolution, correlation, DFT, spectrum, differentiation, integration and RC low-pass filtering.
Discrete-time signal generation and processing implemented in native C. The module accepts GSVE arrays of finite numeric samples and returns scalar measurements, transformed arrays, or arrays of spectral-bin objects.
The module is a native C shared object. It adds an imported namespace to GSVE; it does not add keywords, alter the parser/compiler, or change the bytecode VM.
Contents
- Build, install and import
- Exported API and signatures
- Practical GSVE examples
- Validation and numerical behavior
Build, install and import
Build the corresponding native module from the greenServeFE build repository using its matching manually triggered GitHub Actions workflow. The workflow's artifact is a build output; it is not automatically installed into every greenServeFE runtime.
# After placing the shared object in this directory:
export GREENSERVE_MODULE_PATH=/usr/local/lib/modules
export LD_LIBRARY_PATH=/usr/local/lib/modules:$LD_LIBRARY_PATH
# In a file named program.gsve:
import gs_signal;
print(gs_signal.info());
For a simple import, the VM searches the current directory, ./modules, the platform loader path, and directories listed in GREENSERVE_MODULE_PATH. The module must be named gs_signal.so in a searched location.
Exported API and signatures
| Export | GSVE call signature | Description |
|---|---|---|
info | gs_signal.info() | Returns module name, version, sample cap and scope. |
sine | sine(frequency_hz, sample_rate_hz, duration_seconds, amplitude?) | Generates sampled sine values; amplitude defaults to 1. |
square | square(frequency_hz, sample_rate_hz, duration_seconds, amplitude?) | Generates a ±amplitude square wave using the sign of a sine wave. |
sawtooth | sawtooth(frequency_hz, sample_rate_hz, duration_seconds, amplitude?) | Generates a rising sawtooth waveform. |
rms | rms(samples) | Root-mean-square amplitude. |
mean | mean(samples) | Arithmetic mean. |
peak | peak(samples) | Maximum absolute sample magnitude. |
peak_to_peak | peak_to_peak(samples) | Maximum sample minus minimum sample. |
energy | energy(samples) | Sum of squared sample values (discrete energy). |
normalize | normalize(samples) | Divides all samples by peak absolute magnitude; zero-only input returns null. |
moving_average | moving_average(samples, window_size) | Trailing moving average with valid windows only; output length N−window+1. |
convolve | convolve(signal, kernel) | Full discrete linear convolution; output length Nx+Ny−1. |
correlation | correlation(x, y) | Pearson-style normalized correlation coefficient; arrays must have equal length and nonzero variance. |
dft | dft(samples) | Direct DFT for bins 0 through floor(N/2); returns objects with real, imag, magnitude and phase. |
spectrum | spectrum(samples, sample_rate_hz?) | One-sided magnitude spectrum; sample rate defaults to 1 Hz. |
derivative | derivative(samples, sample_rate_hz?) | Finite-difference derivative; sample rate defaults to 1 Hz. |
integral | integral(samples, sample_rate_hz) | Cumulative trapezoidal integral; positive sample rate is required. |
lowpass_rc | lowpass_rc(samples, cutoff_hz, sample_rate_hz) | First-order recursive RC low-pass filter; requires 0 < cutoff < sample_rate/2. |
Sampling model and result shapes
Waveform generators compute the sample count as ceil(sample_rate_hz × duration_seconds). Samples are generated at t = index / sample_rate_hz. The waveform APIs return arrays of numbers. dft returns an array of objects with real, imag, magnitude and phase; spectrum returns objects with frequency_hz and magnitude.
For dft and spectrum, only bins from zero through the Nyquist-side index floor(N/2) are returned. The implementation uses a direct O(N²) transform, not an FFT.
Practical GSVE examples
These examples use the implemented GSVE syntax: define declarations, func functions, semicolon-terminated statements, arrays, objects, for value in array iteration, and member calls.
import gs_signal;
define samples = gs_signal.sine(5, 100, 0.2, 2);
print(gs_signal.info());
print(gs_signal.mean(samples));
print(gs_signal.rms(samples));
print(gs_signal.peak(samples));
print(gs_signal.peak_to_peak(samples));
print(gs_signal.energy(samples));
define normalized = gs_signal.normalize(samples);
define smooth = gs_signal.moving_average(samples, 5);
print(normalized);
print(smooth);
define impulse = [1, 0, 0, 0];
define kernel = [0.25, 0.5, 0.25];
define filtered = gs_signal.convolve(impulse, kernel);
print(filtered);
define bins = gs_signal.dft(samples);
print(bins[0].magnitude);
define spectrum = gs_signal.spectrum(samples, 100);
print(spectrum[0].frequency_hz);
define slope = gs_signal.derivative(samples, 100);
define area = gs_signal.integral(samples, 100);
print(slope);
print(area);
define low = gs_signal.lowpass_rc(samples, 10, 100);
print(low);
Validation, limits and numerical behavior
- Sample inputs must be non-empty arrays containing only finite numbers. The maximum input length is 4096 samples.
- Waveform arguments require frequency ≥ 0, sample rate > 0 and duration > 0; optional amplitude defaults to 1. Generated sample count must be between 1 and 4096.
moving_averagerequires an integer window size from 1 through the sample count and returns only complete windows.convolvereturns full linear convolution and rejects a result longer than 4096 values.correlationrequires equal-length arrays and nonzero variance in both signals; otherwise it returns null.normalizereturns null for an all-zero input because its peak magnitude is zero.integralrequires an explicit positive sample rate.derivativeandspectrumdefault their sample rate to 1 when omitted.lowpass_rcrequires 0 < cutoff frequency < Nyquist frequency (sample_rate/2). Its implementation is a first-order recursive RC smoothing filter.- The DFT and convolution implementations are direct algorithms; there is no FFT acceleration, streaming interface, windowing, or anti-aliasing stage in this module.
null for invalid types, missing required numeric arguments, non-finite values, invalid domains, or resource-limit violations. Check inputs before using results in subsequent calculations.VM and runtime relationship
GSVE source passes through the lexer, parser/AST, bytecode compiler and VM. Imported module functions are native function values stored in the module object. Calls such as gs_signal.info() are ordinary GSVE member access and function-call expressions; the VM dispatches them through the native function interface. Arrays and objects passed to native functions are GSVE runtime values, not C pointers exposed to the script.
Use greenServeFE --dump program.gsve to inspect compiled bytecode, greenServeFE --trace program.gsve to trace VM execution, and greenServeFE --profile program.gsve to collect opcode and function profiling data. These options inspect VM execution; they do not profile individual C instructions inside this module.
