greenServeFE logogreenServeFELanguage, VM and Native Module Reference

Documentation home / Native modules / gs_signal

Native C module API · ABI version 1

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.

Module scope

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

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

ExportGSVE call signatureDescription
infogs_signal.info()Returns module name, version, sample cap and scope.
sinesine(frequency_hz, sample_rate_hz, duration_seconds, amplitude?)Generates sampled sine values; amplitude defaults to 1.
squaresquare(frequency_hz, sample_rate_hz, duration_seconds, amplitude?)Generates a ±amplitude square wave using the sign of a sine wave.
sawtoothsawtooth(frequency_hz, sample_rate_hz, duration_seconds, amplitude?)Generates a rising sawtooth waveform.
rmsrms(samples)Root-mean-square amplitude.
meanmean(samples)Arithmetic mean.
peakpeak(samples)Maximum absolute sample magnitude.
peak_to_peakpeak_to_peak(samples)Maximum sample minus minimum sample.
energyenergy(samples)Sum of squared sample values (discrete energy).
normalizenormalize(samples)Divides all samples by peak absolute magnitude; zero-only input returns null.
moving_averagemoving_average(samples, window_size)Trailing moving average with valid windows only; output length N−window+1.
convolveconvolve(signal, kernel)Full discrete linear convolution; output length Nx+Ny−1.
correlationcorrelation(x, y)Pearson-style normalized correlation coefficient; arrays must have equal length and nonzero variance.
dftdft(samples)Direct DFT for bins 0 through floor(N/2); returns objects with real, imag, magnitude and phase.
spectrumspectrum(samples, sample_rate_hz?)One-sided magnitude spectrum; sample rate defaults to 1 Hz.
derivativederivative(samples, sample_rate_hz?)Finite-difference derivative; sample rate defaults to 1 Hz.
integralintegral(samples, sample_rate_hz)Cumulative trapezoidal integral; positive sample rate is required.
lowpass_rclowpass_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.

The hard sample-array cap is 4096 elements. Generated waveforms and output arrays are bounded by this limit. The direct DFT can become expensive well before the maximum length; use modest sample counts for interactive examples.

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

Native module functions validate their inputs and return GSVE 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.

Related references