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)
Physical low-bit storage for a logical behavior-adaptation bank.
Parameters
valuestorch.Tensor- required. Physical quantized values, interpreted using the bank's scale and layout metadata.
scalestorch.Tensor- required. Floating-point reconstruction scales for the stored quantized values.
bitsint- required. Quantization precision, restricted to the supported bit widths.
logical_parameters_per_neuronint- 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)
Component-wise W4/W8 storage for a logical adaptation bank.
Parameters
valuestorch.Tensor- required. Physical quantized values, interpreted using the bank's scale and layout metadata.
scalestorch.Tensor- required. Floating-point reconstruction scales for the stored quantized values.
byte_slicesdict[str, slice]- required.
component_bitsdict[str, int]- required. Mapping from adaptation component names to supported W4/W8 storage widths.
logical_parameters_per_neuronint- 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
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
parameterstorch.Tensor- required. Floating-point adaptation rows before quantization.
adaptationNeuronBehaviorAdaptation- keyword-only, required. Descriptor defining named behavior components and their logical shapes.
bitsint- 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
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
parameterstorch.Tensor- required. Floating-point adaptation rows before quantization.
adaptationNeuronBehaviorAdaptation- keyword-only, required. Descriptor defining named behavior components and their logical shapes.
component_bitsdict[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
Materialize a low-bit behavior bank for validation or export.
Parameters
bankQuantizedNeuronBehaviorBank- required. Quantized bank including its scale and layout metadata.
adaptationNeuronBehaviorAdaptation- keyword-only, required. Descriptor defining named behavior components and their logical shapes.
Returns
parameterstorch.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
Materialize a component-wise W4/W8 adaptation bank.
Parameters
bankMixedQuantizedNeuronBehaviorBank- required. Quantized bank including its scale and layout metadata.
adaptationNeuronBehaviorAdaptation- keyword-only, required. Descriptor defining named behavior components and their logical shapes.
Returns
parameterstorch.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
Pack a trained behavior adapter into the population ABI.
Parameters
adapterNeuronBehaviorAdapter- required. Behavior adapter whose named components define the population bank.
adaptationNeuronBehaviorAdaptation- 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)
Compiled persistent-state inference for a shared-weight GRU population.
Parameters
modelAxoTemporalModel- required. Model to execute, optimize, count, or serialize for this operation.
populationint- keyword-only, required. Number of neurons represented by the population runner or record.
chunk_sizeint- keyword-only, required. Chunk length for the supported Mamba or streaming execution path.
compile_stepbool- keyword-only, default=True. Compile the population step implementation.
compile_modestr- keyword-only, default='reduce-overhead'. Mode passed to torch.compile for the selected step.
population_embedding_adapterstorch.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
Advance the population runner by one declared simulation step.
Parameters
event_indicestorch.Tensor- required.
event_valuestorch.Tensor- required. Signed floating-point event amplitudes, one per paired address.
morphology_indicestorch.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)
Compiled GRU inference from pre-aggregated raw branch inputs.
Bases: GRUPopulationRunner.
Parameters
modelAxoTemporalModel- required. Model to execute, optimize, count, or serialize for this operation.
populationint- keyword-only, required. Number of neurons represented by the population runner or record.
chunk_sizeint- keyword-only, required. Chunk length for the supported Mamba or streaming execution path.
compile_stepbool- keyword-only, default=True. Compile the population step implementation.
compile_modestr- keyword-only, default='reduce-overhead'. Mode passed to torch.compile for the selected step.
population_embedding_adapterstorch.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
Advance the population runner by one declared simulation step.
Parameters
branch_inputstorch.Tensor- required. Current population branch-feature tensor.
morphology_indicestorch.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')
Packed per-neuron behavior adaptation around one shared GRU base.
Bases: GRUBranchPopulationRunner.
Parameters
modelAxoTemporalModel- required. Model to execute, optimize, count, or serialize for this operation.
populationint- keyword-only, required. Number of neurons represented by the population runner or record.
chunk_sizeint- keyword-only, required. Chunk length for the supported Mamba or streaming execution path.
behavior_parameterstorch.Tensor | QuantizedNeuronBehaviorBank | MixedQuantizedNeuronBehaviorBank- keyword-only, required. Logical behavior coefficients to compile into the model's deployed coefficient width.
adaptationNeuronBehaviorAdaptation- keyword-only, required. Descriptor defining named behavior components and their logical shapes.
compile_stepbool- keyword-only, default=True. Compile the population step implementation.
compile_modestr- 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
Advance the population runner by one declared simulation step.
Parameters
branch_inputstorch.Tensor- required. Current population branch-feature tensor.
morphology_indicestorch.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')
Compiled GRU inference with one recurrent parameter set per group.
Parameters
modelAxoTemporalModel- required. Model to execute, optimize, count, or serialize for this operation.
populationint- keyword-only, required. Number of neurons represented by the population runner or record.
groupsint- keyword-only, required. Population parameter-group count.
chunk_sizeint- keyword-only, required. Chunk length for the supported Mamba or streaming execution path.
compile_stepbool- keyword-only, default=True. Compile the population step implementation.
compile_modestr- 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
Advance the population runner by one declared simulation step.
Parameters
event_indicestorch.Tensor- required.
event_valuestorch.Tensor- required. Signed floating-point event amplitudes, one per paired address.
morphology_indicestorch.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
Load one group’s recurrent weights from a compatible GRU model.
Parameters
groupint- required. Index of the population parameter group to load.
sourceAxoTemporalModel- required.
Returns
resultNone- No return value.
NeuronBehaviorAdaptation
axosim.deployment.NeuronBehaviorAdaptation(width: int, branches: int, outputs: int, matrix_rank: int, adapt_recurrent: bool, branch_token_offset: bool = False)
Mechanism-level parameters that remain unique to each neuron.
Parameters
widthint- required. Feature width of the behavior adapter or population recurrence.
branchesint- required. Number of routed branch features in the adapter.
outputsint- required. Number of readout channels.
matrix_rankint- required.
adapt_recurrentbool- required.
branch_token_offsetbool- 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
- 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)
One complete population-simulation measurement.
Parameters
populationint- required. Number of neurons represented by the population runner or record.
adapted_parameters_per_neuronint- required.
adapted_componentstuple[str, ...]- required.
shared_componentstuple[str, ...]- required.
unique_adaptation_per_neuronbool- required.
adaptation_quality_validatedbool- required.
shared_frozen_basebool- required.
output_materializedbool- required.
routing_feeds_modelbool- required.
model_latency_msfloat- required.
routing_latency_msfloat | None- required.
complete_stack_latency_msfloat | None- required.
model_peak_bytesint- required.
routing_peak_bytesint | None- required.
complete_stack_peak_bytesint | None- required.
local_source_identity_retainedbool- default=False.
long_range_source_identity_retainedbool- default=False.
morphology_assignment_independentbool- default=False.
activity_generation_modestr- default='unknown'.
activity_dynamics_validatedbool- default=False.
adaptation_execution_modestr- default='direct'.
adaptation_reference_envelope_validatedbool- default=False.
forecast_block_sizeint- default=1.
complete_block_latency_msfloat | 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)
Requirements for a defensible real-time population claim.
Parameters
headline_populationint- required.
benchmark_populationint- required.
biological_step_msfloat- required.
adaptationNeuronBehaviorAdaptation- required. Descriptor defining named behavior components and their logical shapes.
shared_frozen_basebool- required.
output_materialization_requiredbool- required.
network_routing_requiredbool- required.
local_source_identity_requiredbool- required.
long_range_source_identity_requiredbool- required.
independent_morphology_assignment_requiredbool- required.
activity_dynamics_validation_requiredbool- required.
quota_activity_allowedbool- required.
forecast_block_sizeint- required.
firing_ratefloat- required.
fanoutint- 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, ...]
Return violated deployment requirements for the supplied measurement.
Parameters
measurementPopulationDeploymentMeasurement- 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]
Compare a deployment measurement with the declared target requirements.
Parameters
measurementPopulationDeploymentMeasurement- required. Measured deployment record to compare with the target requirements.
Returns
dict[str, int \| float \| bool]