MayaFlux::Nodes::NodeNetwork Class Reference

Abstract base class for structured collections of nodes with defined relationships. More...

#include <NodeNetwork.hpp>

Inheritance diagram for MayaFlux::Nodes::NodeNetwork:

Collaboration diagram for MayaFlux::Nodes::NodeNetwork:

Classes
struct	ParameterMapping

Public Types
enum class	Topology : uint8_t {   INDEPENDENT , CHAIN , RING , GRID_2D ,   GRID_3D , SPATIAL , CUSTOM }
	Defines the structural relationships between nodes in the network. More...
enum class	OutputMode : uint8_t { NONE , AUDIO_SINK , GRAPHICS_BIND , CUSTOM }
	Defines how the network's computational results are exposed. More...
enum class	MappingMode : uint8_t { BROADCAST , ONE_TO_ONE }
	Defines how nodes map to external entities (e.g., audio channels, graphics objects) More...

Public Member Functions
virtual	~NodeNetwork ()=default
virtual void	process_batch (unsigned int num_samples)=0
	Process the network for the given number of samples.
virtual size_t	get_node_count () const =0
	Get the number of nodes in the network.
virtual std::optional< std::vector< double > >	get_audio_buffer () const
	Get cached audio buffer from last process_batch()
void	set_output_mode (OutputMode mode)
	Set the network's output routing mode.
OutputMode	get_output_mode () const
	Get the current output routing mode.
void	set_topology (Topology topology)
	Set the network's topology.
Topology	get_topology () const
	Get the current topology.
void	set_enabled (bool enabled)
	Enable/disable the network.
bool	is_enabled () const
	Check if network is enabled.
virtual std::unordered_map< std::string, std::string >	get_metadata () const
	Get network metadata for debugging/visualization.
virtual std::optional< double >	get_node_output (size_t index) const
	Get output of specific internal node (for ONE_TO_ONE mapping)
virtual void	initialize ()
	Called once before first process_batch()
virtual void	reset ()
	Reset network to initial state.
virtual void	map_parameter (const std::string &param_name, const std::shared_ptr< Node > &source, MappingMode mode=MappingMode::BROADCAST)
	Map external node output to network parameter.
virtual void	map_parameter (const std::string &param_name, const std::shared_ptr< NodeNetwork > &source_network)
	Map external node network to network parameters (ONE_TO_ONE)
virtual void	unmap_parameter (const std::string &param_name)
	Remove parameter mapping.
void	add_channel_usage (uint32_t channel_id)
	Register network usage on a specific channel.
void	remove_channel_usage (uint32_t channel_id)
	Unregister network from a specific channel.
bool	is_registered_on_channel (uint32_t channel_id) const
	Check if network is registered on a channel.
std::vector< uint32_t >	get_registered_channels () const
	Get all channels this network is registered on.
uint32_t	get_channel_mask () const
	Get channel mask (bitfield of registered channels)
void	set_channel_mask (uint32_t mask)
	Set channel mask directly.
bool	is_processed_this_cycle () const
	Check if network has been processed this cycle (lock-free)
void	mark_processing (bool processing)
	Mark network as processing or not (lock-free)
void	mark_processed (bool processed)
	Mark network as processed this cycle (lock-free)
bool	is_processing () const
	Check if network is currently processing (lock-free)

Protected Member Functions
void	ensure_initialized ()
	Ensure initialize() is called exactly once.

Static Protected Member Functions
static std::unordered_map< size_t, std::vector< size_t > >	build_grid_2d_neighbors (size_t width, size_t height)
	Build neighbor map for GRID_2D topology.
static std::unordered_map< size_t, std::vector< size_t > >	build_grid_3d_neighbors (size_t width, size_t height, size_t depth)
	Build neighbor map for GRID_3D topology.
static std::unordered_map< size_t, std::vector< size_t > >	build_ring_neighbors (size_t count)
	Build neighbor map for RING topology.
static std::unordered_map< size_t, std::vector< size_t > >	build_chain_neighbors (size_t count)
	Build neighbor map for CHAIN topology.

Protected Attributes
Topology	m_topology = Topology::INDEPENDENT
OutputMode	m_output_mode = OutputMode::NONE
bool	m_enabled = true
bool	m_initialized = false
std::vector< ParameterMapping >	m_parameter_mappings
std::atomic< uint32_t >	m_channel_mask { 0 }
	Bitfield of channels this network is registered on.
std::atomic< bool >	m_processing_state { false }
	Per-channel processing state (lock-free atomic flags)
std::atomic< bool >	m_processed_this_cycle { false }
std::vector< double >	m_last_audio_buffer

Static Private Member Functions
static std::string	topology_to_string (Topology topo)
static std::string	output_mode_to_string (OutputMode mode)

Detailed Description

Abstract base class for structured collections of nodes with defined relationships.

DESIGN PRINCIPLES:

1. OWNERSHIP: Networks own their nodes exclusively. Nodes within a network cannot be independently attached to NodeGraphManager channels.
2. PROCESSING: Networks are processed directly by NodeGraphManager, parallel to RootNodes. They are NOT summed through RootNode but manage their own internal processing pipeline.
3. OUTPUT ROUTING: Networks explicitly declare their output mode:
   • NONE: Pure internal computation (e.g., particle physics state)
   • AUDIO_SINK: Contributes to audio output (aggregated samples)
   • GRAPHICS_BIND: Data available for visualization (read-only)
   • CUSTOM: User-defined handling via callbacks
4. TOPOLOGY: Networks define relationships between nodes:
   • INDEPENDENT: No inter-node connections
   • CHAIN: Linear sequence (node[i] → node[i+1])
   • RING: Circular (last connects to first)
   • GRID_2D/3D: Spatial lattice with neighbor connections
   • SPATIAL: Dynamic proximity-based relationships
   • CUSTOM: Arbitrary user-defined topology
5. EXTENSIBILITY: Subclasses define:
   • Internal node data structure (spatial, physical, abstract)
   • Interaction behavior (forces, coupling, feedback)
   • Aggregation logic (how to combine node outputs)
   • Initialization patterns (how to populate the network)

PHILOSOPHY:

NodeNetworks embody "structure IS content" - the relationships between nodes define emergent behavior. They bridge individual node computation with collective, coordinated behavior patterns (swarms, resonances, waveguides, recursive growth).

Networks are NOT:

• Buffers (no sequential data storage)
• Processors (no transformation pipelines)
• Simple node containers (relationships matter)

Networks ARE:

• Relational structures for coordinated node behavior
• Generators of emergent complexity from simple rules
• Cross-domain abstractions (audio, visual, control unified)

USAGE PATTERN:

// Create network via builder or subclass constructor
auto particles = std::make_shared<ParticleNetwork>(1000);
particles->set_output_mode(OutputMode::GRAPHICS_BIND);
particles->initialize_random_positions();
 
// Register with NodeGraphManager (NOT RootNode)
node_graph_manager->add_network(particles, ProcessingToken::VISUAL_RATE);
 
// NodeGraphManager calls process_batch() each frame
// Graphics nodes can read network state for visualization
auto geom = std::make_shared<NetworkGeometryNode>(particles);

Definition at line 77 of file NodeNetwork.hpp.

---

The documentation for this class was generated from the following files:

• NodeNetwork.hpp
• NodeNetwork.cpp
• ParticleNetwork.cpp