spectral_shells.h File Reference

Spectral-shell stimulus: random annular bands in k-space. More...

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

Include dependency graph for spectral_shells.h:

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

Go to the source code of this file.

Classes
struct	SimStimulusSpectralShellsConfig
	Configuration for seeded random modes sampled from spectral shells. More...

Typedefs
typedef struct SimStimulusSpectralShellsConfig	SimStimulusSpectralShellsConfig
	Configuration for seeded random modes sampled from spectral shells.

Functions
SimResult	sim_add_stimulus_spectral_shells_operator (struct SimContext *context, const SimStimulusSpectralShellsConfig *config, size_t *out_index)
	Register a random spectral-shell stimulus operator.
SimResult	sim_stimulus_spectral_shells_config (struct SimContext *context, size_t operator_index, SimStimulusSpectralShellsConfig *out_config)
	Copy the current spectral-shells configuration from a registered operator.
SimResult	sim_stimulus_spectral_shells_update (struct SimContext *context, size_t operator_index, const SimStimulusSpectralShellsConfig *config)
	Replace or renormalize a registered spectral-shells configuration.

Detailed Description

Spectral-shell stimulus: random annular bands in k-space.

Synthesizes spatial fields from seeded Fourier modes sampled within concentric k-space shells (annuli). For 1D fields, shell radii map to signed 1D wavenumbers; for 2D fields, shell radii map to random angles.

Function Documentation

sim_add_stimulus_spectral_shells_operator()

SimResult sim_add_stimulus_spectral_shells_operator	(	struct SimContext *	context,
		const SimStimulusSpectralShellsConfig *	config,
		size_t *	out_index
	)

Register a random spectral-shell stimulus operator.

The implementation copies and normalizes config, builds deterministic shell modes from the seed, and registers the operator on the target field.

Parameters

	context	Simulation context that will own the operator.
	config	Optional spectral-shells 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, mode setup, or split-operator registration.

sim_stimulus_spectral_shells_config()

SimResult sim_stimulus_spectral_shells_config	(	struct SimContext *	context,
		size_t	operator_index,
		SimStimulusSpectralShellsConfig *	out_config
	)

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

Parameters

	context	Simulation context containing the operator.
	operator_index	Index returned by sim_add_stimulus_spectral_shells_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_shells_update()

SimResult sim_stimulus_spectral_shells_update	(	struct SimContext *	context,
		size_t	operator_index,
		const SimStimulusSpectralShellsConfig *	config
	)

Replace or renormalize a registered spectral-shells configuration.

Passing NULL for config keeps the existing configuration and reapplies normalization. A successful update rebuilds shell modes as needed and invalidates the scheduler plan.

Parameters

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

Returns

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