API reference

Behavior banks and population runners

Signatures, parameters, return contracts, and source for behavior banks and population runners.

Overview

Behavior-bank quantization stores component scales and W4/W8 values separately from the shared model. Quantization is a deployment transformation, while training uses floating-point parameters. The low-level GRU population runners and deployment records expose the contracts used for direct runtime construction.

Source revision: caef7be03abd. Public export index.

QuantizedNeuronBehaviorBank

axosim.population.QuantizedNeuronBehaviorBank(values: torch.Tensor, scales: torch.Tensor, bits: int, logical_parameters_per_neuron: int)

Source

Physical low-bit storage for a logical behavior-adaptation bank.

Parameters

values torch.Tensor
required. Physical quantized values, interpreted using the bank's scale and layout metadata.
scales torch.Tensor
required. Floating-point reconstruction scales for the stored quantized values.
bits int
required. Quantization precision, restricted to the supported bit widths.
logical_parameters_per_neuron int
required.

Attributes

Constructor fields are retained as read-only attributes.

Read-only attributes

QuantizedNeuronBehaviorBank.storage_bytes: int
Physical bank storage, including quantized values and reconstruction scales. Source

MixedQuantizedNeuronBehaviorBank

axosim.population.MixedQuantizedNeuronBehaviorBank(values: torch.Tensor, scales: torch.Tensor, byte_slices: dict[str, slice], component_bits: dict[str, int], logical_parameters_per_neuron: int)

Source

Component-wise W4/W8 storage for a logical adaptation bank.

Parameters

values torch.Tensor
required. Physical quantized values, interpreted using the bank's scale and layout metadata.
scales torch.Tensor
required. Floating-point reconstruction scales for the stored quantized values.
byte_slices dict[str, slice]
required.
component_bits dict[str, int]
required. Mapping from adaptation component names to supported W4/W8 storage widths.
logical_parameters_per_neuron int
required.

Attributes

Constructor fields are retained as read-only attributes.

Read-only attributes

MixedQuantizedNeuronBehaviorBank.storage_bytes: int
Physical bank storage, including quantized values and reconstruction scales. Source

quantize_neuron_behavior_parameters

axosim.population.quantize_neuron_behavior_parameters(parameters: torch.Tensor, *, adaptation: NeuronBehaviorAdaptation, bits: int) -> QuantizedNeuronBehaviorBank

Source

Quantize each adaptation component with one symmetric scale.

parameters is floating-point (N,adaptation.parameter_count). bits is 4 or 8. W4 requires even logical width and packs two values per byte. Returns physical values and one scale per adaptation component.

Parameters

parameters torch.Tensor
required. Floating-point adaptation rows before quantization.
adaptation NeuronBehaviorAdaptation
keyword-only, required. Descriptor defining named behavior components and their logical shapes.
bits int
keyword-only, required. Quantization precision, restricted to the supported bit widths.

Returns

QuantizedNeuronBehaviorBank

quantize_mixed_neuron_behavior_parameters

axosim.population.quantize_mixed_neuron_behavior_parameters(parameters: torch.Tensor, *, adaptation: NeuronBehaviorAdaptation, component_bits: dict[str, int]) -> MixedQuantizedNeuronBehaviorBank

Source

Quantize each adaptation component to its declared W4/W8 tier.

parameters is floating-point (N,adaptation.parameter_count). component_bits declares W4/W8 for each named adaptation component. Returns packed byte slices and scale metadata needed for reconstruction.

Parameters

parameters torch.Tensor
required. Floating-point adaptation rows before quantization.
adaptation NeuronBehaviorAdaptation
keyword-only, required. Descriptor defining named behavior components and their logical shapes.
component_bits dict[str, int]
keyword-only, required. Mapping from adaptation component names to supported W4/W8 storage widths.

Returns

MixedQuantizedNeuronBehaviorBank

dequantize_neuron_behavior_parameters

axosim.population.dequantize_neuron_behavior_parameters(bank: QuantizedNeuronBehaviorBank, *, adaptation: NeuronBehaviorAdaptation) -> torch.Tensor

Source

Materialize a low-bit behavior bank for validation or export.

Parameters

bank QuantizedNeuronBehaviorBank
required. Quantized bank including its scale and layout metadata.
adaptation NeuronBehaviorAdaptation
keyword-only, required. Descriptor defining named behavior components and their logical shapes.

Returns

parameters torch.Tensor
Floating-point behavior rows (population,adaptation.parameter_count), reconstructed component by component.

dequantize_mixed_neuron_behavior_parameters

axosim.population.dequantize_mixed_neuron_behavior_parameters(bank: MixedQuantizedNeuronBehaviorBank, *, adaptation: NeuronBehaviorAdaptation) -> torch.Tensor

Source

Materialize a component-wise W4/W8 adaptation bank.

Parameters

bank MixedQuantizedNeuronBehaviorBank
required. Quantized bank including its scale and layout metadata.
adaptation NeuronBehaviorAdaptation
keyword-only, required. Descriptor defining named behavior components and their logical shapes.

Returns

parameters torch.Tensor
Floating-point behavior rows (population,adaptation.parameter_count), reconstructed from each component's W4/W8 slice.

pack_neuron_behavior_adapter

axosim.population.pack_neuron_behavior_adapter(adapter: NeuronBehaviorAdapter, *, adaptation: NeuronBehaviorAdaptation) -> torch.Tensor

Source

Pack a trained behavior adapter into the population ABI.

Parameters

adapter NeuronBehaviorAdapter
required. Behavior adapter whose named components define the population bank.
adaptation NeuronBehaviorAdaptation
keyword-only, required. Descriptor defining named behavior components and their logical shapes.

Returns

torch.Tensor

GRUPopulationRunner

axosim.population.GRUPopulationRunner(model: AxoTemporalModel, *, population: int, chunk_size: int, compile_step: bool=True, compile_mode: str='reduce-overhead', population_embedding_adapters: torch.Tensor | None=None)

Source

Compiled persistent-state inference for a shared-weight GRU population.

Parameters

model AxoTemporalModel
required. Model to execute, optimize, count, or serialize for this operation.
population int
keyword-only, required. Number of neurons represented by the population runner or record.
chunk_size int
keyword-only, required. Chunk length for the supported Mamba or streaming execution path.
compile_step bool
keyword-only, default=True. Compile the population step implementation.
compile_mode str
keyword-only, default='reduce-overhead'. Mode passed to torch.compile for the selected step.
population_embedding_adapters torch.Tensor | None
keyword-only, default=None. Population-group embedding corrections for the backbone.

Read-only attributes

GRUPopulationRunner.recurrent_state: torch.Tensor
Source
GRUPopulationRunner.patch_sum: torch.Tensor | None
Source
GRUPopulationRunner.patch_correction: torch.Tensor | None
Source
GRUPopulationRunner.patch_position: int
Source

Methods

GRUPopulationRunner.step

axosim.population.GRUPopulationRunner.step(event_indices: torch.Tensor, event_values: torch.Tensor, morphology_indices: torch.Tensor) -> torch.Tensor

Source

Advance the population runner by one declared simulation step.

Parameters

event_indices torch.Tensor
required.
event_values torch.Tensor
required. Signed floating-point event amplitudes, one per paired address.
morphology_indices torch.Tensor
required. Integer class assignments into the model's ordered morphology vocabulary; one per batch item or persistent neuron.

Returns

torch.Tensor

GRUBranchPopulationRunner

axosim.population.GRUBranchPopulationRunner(model: AxoTemporalModel, *, population: int, chunk_size: int, compile_step: bool=True, compile_mode: str='reduce-overhead', population_embedding_adapters: torch.Tensor | None=None)

Source

Compiled GRU inference from pre-aggregated raw branch inputs.

Bases: GRUPopulationRunner.

Parameters

model AxoTemporalModel
required. Model to execute, optimize, count, or serialize for this operation.
population int
keyword-only, required. Number of neurons represented by the population runner or record.
chunk_size int
keyword-only, required. Chunk length for the supported Mamba or streaming execution path.
compile_step bool
keyword-only, default=True. Compile the population step implementation.
compile_mode str
keyword-only, default='reduce-overhead'. Mode passed to torch.compile for the selected step.
population_embedding_adapters torch.Tensor | None
keyword-only, default=None. Population-group embedding corrections for the backbone.

Methods

GRUBranchPopulationRunner.step

axosim.population.GRUBranchPopulationRunner.step(branch_inputs: torch.Tensor, morphology_indices: torch.Tensor) -> torch.Tensor

Source

Advance the population runner by one declared simulation step.

Parameters

branch_inputs torch.Tensor
required. Current population branch-feature tensor.
morphology_indices torch.Tensor
required. Integer class assignments into the model's ordered morphology vocabulary; one per batch item or persistent neuron.

Returns

torch.Tensor

AdaptedGRUBranchPopulationRunner

axosim.population.AdaptedGRUBranchPopulationRunner(model: AxoTemporalModel, *, population: int, chunk_size: int, behavior_parameters: torch.Tensor | QuantizedNeuronBehaviorBank | MixedQuantizedNeuronBehaviorBank, adaptation: NeuronBehaviorAdaptation, compile_step: bool=True, compile_mode: str='max-autotune-no-cudagraphs')

Source

Packed per-neuron behavior adaptation around one shared GRU base.

Bases: GRUBranchPopulationRunner.

Parameters

model AxoTemporalModel
required. Model to execute, optimize, count, or serialize for this operation.
population int
keyword-only, required. Number of neurons represented by the population runner or record.
chunk_size int
keyword-only, required. Chunk length for the supported Mamba or streaming execution path.
behavior_parameters torch.Tensor | QuantizedNeuronBehaviorBank | MixedQuantizedNeuronBehaviorBank
keyword-only, required. Logical behavior coefficients to compile into the model's deployed coefficient width.
adaptation NeuronBehaviorAdaptation
keyword-only, required. Descriptor defining named behavior components and their logical shapes.
compile_step bool
keyword-only, default=True. Compile the population step implementation.
compile_mode str
keyword-only, default='max-autotune-no-cudagraphs'. Mode passed to torch.compile for the selected step.

Methods

AdaptedGRUBranchPopulationRunner.step

axosim.population.AdaptedGRUBranchPopulationRunner.step(branch_inputs: torch.Tensor, morphology_indices: torch.Tensor) -> torch.Tensor

Source

Advance the population runner by one declared simulation step.

Parameters

branch_inputs torch.Tensor
required. Current population branch-feature tensor.
morphology_indices torch.Tensor
required. Integer class assignments into the model's ordered morphology vocabulary; one per batch item or persistent neuron.

Returns

torch.Tensor

GroupedGRUPopulationRunner

axosim.population.GroupedGRUPopulationRunner(model: AxoTemporalModel, *, population: int, groups: int, chunk_size: int, compile_step: bool=True, compile_mode: str='reduce-overhead')

Source

Compiled GRU inference with one recurrent parameter set per group.

Parameters

model AxoTemporalModel
required. Model to execute, optimize, count, or serialize for this operation.
population int
keyword-only, required. Number of neurons represented by the population runner or record.
groups int
keyword-only, required. Population parameter-group count.
chunk_size int
keyword-only, required. Chunk length for the supported Mamba or streaming execution path.
compile_step bool
keyword-only, default=True. Compile the population step implementation.
compile_mode str
keyword-only, default='reduce-overhead'. Mode passed to torch.compile for the selected step.

Read-only attributes

GroupedGRUPopulationRunner.resident_parameter_count: int
Source
GroupedGRUPopulationRunner.patch_position: int
Source

Methods

GroupedGRUPopulationRunner.step

axosim.population.GroupedGRUPopulationRunner.step(event_indices: torch.Tensor, event_values: torch.Tensor, morphology_indices: torch.Tensor) -> torch.Tensor

Source

Advance the population runner by one declared simulation step.

Parameters

event_indices torch.Tensor
required.
event_values torch.Tensor
required. Signed floating-point event amplitudes, one per paired address.
morphology_indices torch.Tensor
required. Integer class assignments into the model's ordered morphology vocabulary; one per batch item or persistent neuron.

Returns

torch.Tensor

GroupedGRUPopulationRunner.load_group_recurrent_parameters

axosim.population.GroupedGRUPopulationRunner.load_group_recurrent_parameters(group: int, source: AxoTemporalModel) -> None

Source

Load one group’s recurrent weights from a compatible GRU model.

Parameters

group int
required. Index of the population parameter group to load.
source AxoTemporalModel
required.

Returns

result None
No return value.

NeuronBehaviorAdaptation

axosim.deployment.NeuronBehaviorAdaptation(width: int, branches: int, outputs: int, matrix_rank: int, adapt_recurrent: bool, branch_token_offset: bool = False)

Source

Mechanism-level parameters that remain unique to each neuron.

Parameters

width int
required. Feature width of the behavior adapter or population recurrence.
branches int
required. Number of routed branch features in the adapter.
outputs int
required. Number of readout channels.
matrix_rank int
required.
adapt_recurrent bool
required.
branch_token_offset bool
default=False. Include adaptation offsets for encoded branch tokens.

Attributes

Constructor fields are retained as read-only attributes.

Read-only attributes

NeuronBehaviorAdaptation.tensor_shapes: dict[str, tuple[int, ...]]
Source
NeuronBehaviorAdaptation.tensor_slices: dict[str, slice]
Source
NeuronBehaviorAdaptation.parameter_counts: dict[str, int]
Source
NeuronBehaviorAdaptation.parameter_count: int
Source
NeuronBehaviorAdaptation.adapted_components: frozenset[str]
Source
NeuronBehaviorAdaptation.shared_components: frozenset[str]
Source

PopulationDeploymentMeasurement

axosim.deployment.PopulationDeploymentMeasurement(population: int, adapted_parameters_per_neuron: int, adapted_components: tuple[str, ...], shared_components: tuple[str, ...], unique_adaptation_per_neuron: bool, adaptation_quality_validated: bool, shared_frozen_base: bool, output_materialized: bool, routing_feeds_model: bool, model_latency_ms: float, routing_latency_ms: float | None, complete_stack_latency_ms: float | None, model_peak_bytes: int, routing_peak_bytes: int | None, complete_stack_peak_bytes: int | None, local_source_identity_retained: bool = False, long_range_source_identity_retained: bool = False, morphology_assignment_independent: bool = False, activity_generation_mode: str = 'unknown', activity_dynamics_validated: bool = False, adaptation_execution_mode: str = 'direct', adaptation_reference_envelope_validated: bool = False, forecast_block_size: int = 1, complete_block_latency_ms: float | None = None)

Source

One complete population-simulation measurement.

Parameters

population int
required. Number of neurons represented by the population runner or record.
adapted_parameters_per_neuron int
required.
adapted_components tuple[str, ...]
required.
shared_components tuple[str, ...]
required.
unique_adaptation_per_neuron bool
required.
adaptation_quality_validated bool
required.
shared_frozen_base bool
required.
output_materialized bool
required.
routing_feeds_model bool
required.
model_latency_ms float
required.
routing_latency_ms float | None
required.
complete_stack_latency_ms float | None
required.
model_peak_bytes int
required.
routing_peak_bytes int | None
required.
complete_stack_peak_bytes int | None
required.
local_source_identity_retained bool
default=False.
long_range_source_identity_retained bool
default=False.
morphology_assignment_independent bool
default=False.
activity_generation_mode str
default='unknown'.
activity_dynamics_validated bool
default=False.
adaptation_execution_mode str
default='direct'.
adaptation_reference_envelope_validated bool
default=False.
forecast_block_size int
default=1.
complete_block_latency_ms float | None
default=None.

Attributes

Constructor fields are retained as read-only attributes.

PopulationDeploymentTarget

axosim.deployment.PopulationDeploymentTarget(headline_population: int, benchmark_population: int, biological_step_ms: float, adaptation: NeuronBehaviorAdaptation, shared_frozen_base: bool, output_materialization_required: bool, network_routing_required: bool, local_source_identity_required: bool, long_range_source_identity_required: bool, independent_morphology_assignment_required: bool, activity_dynamics_validation_required: bool, quota_activity_allowed: bool, forecast_block_size: int, firing_rate: float, fanout: int)

Source

Requirements for a defensible real-time population claim.

Parameters

headline_population int
required.
benchmark_population int
required.
biological_step_ms float
required.
adaptation NeuronBehaviorAdaptation
required. Descriptor defining named behavior components and their logical shapes.
shared_frozen_base bool
required.
output_materialization_required bool
required.
network_routing_required bool
required.
local_source_identity_required bool
required.
long_range_source_identity_required bool
required.
independent_morphology_assignment_required bool
required.
activity_dynamics_validation_required bool
required.
quota_activity_allowed bool
required.
forecast_block_size int
required.
firing_rate float
required.
fanout int
required.

Attributes

Constructor fields are retained as read-only attributes.

Read-only attributes

PopulationDeploymentTarget.adapted_parameters_per_neuron: int
Source

Methods

PopulationDeploymentTarget.validation_errors

axosim.deployment.PopulationDeploymentTarget.validation_errors(measurement: PopulationDeploymentMeasurement) -> tuple[str, ...]

Source

Return violated deployment requirements for the supplied measurement.

Parameters

measurement PopulationDeploymentMeasurement
required. Measured deployment record to compare with the target requirements.

Returns

tuple[str, ...]

PopulationDeploymentTarget.evaluate

axosim.deployment.PopulationDeploymentTarget.evaluate(measurement: PopulationDeploymentMeasurement) -> dict[str, int | float | bool]

Source

Compare a deployment measurement with the declared target requirements.

Parameters

measurement PopulationDeploymentMeasurement
required. Measured deployment record to compare with the target requirements.

Returns

dict[str, int \| float \| bool]

Search guides, examples, and API signatures.