spectral_lines.h File Reference

Spectral-line stimulus: pure frequency spikes and multi-line harmonics. More...

#include "coords.h"
#include "oakfield/operator_split.h"
#include <stdbool.h>
#include <stddef.h>

Include dependency graph for spectral_lines.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	SimStimulusSpectralLinesConfig
	Configuration for harmonic spectral-line stimulus fields. More...

Typedefs
typedef enum SimStimulusSpectralLinesTwistKind	SimStimulusSpectralLinesTwistKind
	Harmonic twist strategy for spectral-line sums.
typedef enum SimStimulusSpectralLinesTwistPreset	SimStimulusSpectralLinesTwistPreset
	Preset table family used for Dirichlet-style spectral-line twists.
typedef struct SimStimulusSpectralLinesConfig	SimStimulusSpectralLinesConfig
	Configuration for harmonic spectral-line stimulus fields.

Enumerations
enum	SimStimulusSpectralLinesTwistKind { SIM_SPECTRAL_LINES_TWIST_NONE = 0 , SIM_SPECTRAL_LINES_TWIST_ALTERNATING , SIM_SPECTRAL_LINES_TWIST_DIRICHLET }
	Harmonic twist strategy for spectral-line sums. More...
enum	SimStimulusSpectralLinesTwistPreset { SIM_SPECTRAL_LINES_TWIST_PRESET_PRINCIPAL = 0 , SIM_SPECTRAL_LINES_TWIST_PRESET_CHI4 , SIM_SPECTRAL_LINES_TWIST_PRESET_QUADRATIC , SIM_SPECTRAL_LINES_TWIST_PRESET_TABLE }
	Preset table family used for Dirichlet-style spectral-line twists. More...

Functions
SimResult	sim_add_stimulus_spectral_lines_operator (struct SimContext *context, const SimStimulusSpectralLinesConfig *config, size_t *out_index)
	Register a spectral-line harmonic stimulus operator.
SimResult	sim_stimulus_spectral_lines_config (struct SimContext *context, size_t operator_index, SimStimulusSpectralLinesConfig *out_config)
	Copy the current spectral-lines configuration from a registered operator.
SimResult	sim_stimulus_spectral_lines_update (struct SimContext *context, size_t operator_index, const SimStimulusSpectralLinesConfig *config)
	Replace or renormalize a registered spectral-lines configuration.
SimResult	sim_stimulus_spectral_lines_set_twist_table (struct SimContext *context, size_t operator_index, unsigned int q, const double *chi_re, const double *chi_im, bool zero_non_units)
	Install an explicit Dirichlet-style twist table on a spectral-lines operator.

Detailed Description

Spectral-line stimulus: pure frequency spikes and multi-line harmonics.

Generates sums of spatial harmonics with optional temporal oscillation. For complex fields this yields single-sided spectral lines; for real fields the spectrum is Hermitian-symmetric.

Enumeration Type Documentation

SimStimulusSpectralLinesTwistKind

enum SimStimulusSpectralLinesTwistKind

Harmonic twist strategy for spectral-line sums.

Enumerator
SIM_SPECTRAL_LINES_TWIST_NONE	No harmonic twist; χ(n)=1.
SIM_SPECTRAL_LINES_TWIST_ALTERNATING	Alternating sign twist; χ(n)=(-1)^n.
SIM_SPECTRAL_LINES_TWIST_DIRICHLET	Dirichlet-character-style twist χ(n mod q).

SimStimulusSpectralLinesTwistPreset

enum SimStimulusSpectralLinesTwistPreset

Preset table family used for Dirichlet-style spectral-line twists.

Enumerator
SIM_SPECTRAL_LINES_TWIST_PRESET_PRINCIPAL	Principal character modulo q.
SIM_SPECTRAL_LINES_TWIST_PRESET_CHI4	Real χ4 character (odd residues mod 4).
SIM_SPECTRAL_LINES_TWIST_PRESET_QUADRATIC	Quadratic/Jacobi character (odd q).
SIM_SPECTRAL_LINES_TWIST_PRESET_TABLE	Residue table χ[r], r in [0, q).

Function Documentation

sim_add_stimulus_spectral_lines_operator()

SimResult sim_add_stimulus_spectral_lines_operator	(	struct SimContext *	context,
		const SimStimulusSpectralLinesConfig *	config,
		size_t *	out_index
	)

Register a spectral-line harmonic stimulus operator.

The implementation copies and normalizes config, prepares any harmonic twist coefficients, and registers the operator on the target field.

Parameters

	context	Simulation context that will own the operator.
	config	Optional spectral-lines configuration; NULL selects normalized defaults.
[out]	out_index	Optional destination for the registered operator index.

Returns

SIM_RESULT_OK on success, or an error code from validation, allocation, coefficient setup, or split-operator registration.

sim_stimulus_spectral_lines_config()

SimResult sim_stimulus_spectral_lines_config	(	struct SimContext *	context,
		size_t	operator_index,
		SimStimulusSpectralLinesConfig *	out_config
	)

Copy the current spectral-lines configuration from a registered operator.

Parameters

	context	Simulation context containing the operator.
	operator_index	Index returned by sim_add_stimulus_spectral_lines_operator().
[out]	out_config	Receives the operator's normalized configuration.

Returns

SIM_RESULT_OK on success, SIM_RESULT_INVALID_ARGUMENT for NULL pointers, SIM_RESULT_NOT_FOUND for a missing operator, or SIM_RESULT_INVALID_STATE when the operator has no stimulus state.

sim_stimulus_spectral_lines_set_twist_table()

SimResult sim_stimulus_spectral_lines_set_twist_table	(	struct SimContext *	context,
		size_t	operator_index,
		unsigned int	q,
		const double *	chi_re,
		const double *	chi_im,
		bool	zero_non_units
	)

Install an explicit Dirichlet-style twist table on a spectral-lines operator.

The real table chi_re is required and must contain q entries. The imaginary table chi_im is optional; when supplied, complex twists are used. A successful call replaces the operator's twist table and invalidates cached coefficients.

Parameters

context	Simulation context containing the operator.
operator_index	Index of the spectral-lines operator to update.
q	Modulus and table length; must be greater than zero.
chi_re	Real twist values indexed by residue class.
chi_im	Optional imaginary twist values indexed by residue class.
zero_non_units	When true, residues with gcd(residue, q) != 1 are zeroed.

Returns

SIM_RESULT_OK on success, or an error code if arguments, lookup, allocation, or coefficient setup fails.

sim_stimulus_spectral_lines_update()

SimResult sim_stimulus_spectral_lines_update	(	struct SimContext *	context,
		size_t	operator_index,
		const SimStimulusSpectralLinesConfig *	config
	)

Replace or renormalize a registered spectral-lines configuration.

Passing NULL for config keeps the existing configuration and reapplies normalization. A successful update refreshes twist coefficients as needed and invalidates the scheduler plan.

Parameters

context	Simulation context containing the operator.
operator_index	Index of the spectral-lines operator to update.
config	Optional replacement configuration.

Returns

SIM_RESULT_OK on success, or an error code if lookup, coefficient setup, or state validation fails.