API reference
Population interfaces
Signatures, parameters, return contracts, and source for population interfaces.
Overview
The public differentiable population combines one Lite model with persistent neuron identities, morphology assignments, contact routes, and adaptation banks. AxoSimMamba aliases AxoMamba; AxoSimLite aliases AdaptiveSupportP4Surrogate; AxoSimGRU currently aliases CausalBlockForecastModel. Named GRU profiles are built by create_axosim_profile and return AxoTemporalModel.
Source revision: caef7be03abd. Public export index.
AxoSimPopulation
axosim.interfaces.AxoSimPopulation(neuron: AxoSimLite, *, morphology_indices: torch.Tensor, contact_branch_indices: torch.Tensor)
Differentiable AxoSim-Lite population with distinct adaptation banks.
Bases: nn.Module.
neuron is a Lite model. morphology_indices is integer (N,); contact_branch_indices is integer (N,K), with values in [0, neuron.config.input_dim). The morphology indices must refer to declared morphology classes. Buffers are cloned and converted to long.
Parameters
neuronAxoSimLite- required. Shared Lite neuron used by every persistent population member.
morphology_indicestorch.Tensor- keyword-only, required. Integer class assignments into the model's ordered morphology vocabulary; one per batch item or persistent neuron.
contact_branch_indicestorch.Tensor- keyword-only, required. Integer tensor (population, contacts), mapping each contact to a Lite input channel.
Read-only attributes
AxoSimPopulation.population_size: int- Number of persistent neurons. Source
AxoSimPopulation.runtime_coefficients_per_neuron: int- Width of the direct behavior coefficients for one neuron. Source
AxoSimPopulation.synaptic_efficacies_per_neuron: int- Number of independently mutable incoming contacts per neuron. Source
Methods
AxoSimPopulation.adaptation_parameters()AxoSimPopulation.trainable_adaptation_parameters()AxoSimPopulation.enable_adaptation_training()AxoSimPopulation.enable_full_training()AxoSimPopulation.synaptic_efficacies()AxoSimPopulation.forward()AxoSimPopulation.forward_sparse_contacts()AxoSimPopulation.forward_batch()AxoSimPopulation.forward_tokens()AxoSimPopulation.forward_token_batch()
Examples
Run independent trials through one persistent population.
Download population_example.py into your working directory first; build populations explains its construction.
import torch
from population_example import build_population
population = build_population()
prediction = population.forward_batch(torch.zeros(2, 3, 12, 4))
print(prediction.shape)
torch.Size([2, 3, 12, 2])
AxoSimPopulation.adaptation_parameters
axosim.interfaces.AxoSimPopulation.adaptation_parameters() -> Iterator[nn.Parameter]
Yields behavior_adapter, morphology_adapter, and synaptic_log_efficacy in that order.
Returns
resultIterator[nn.Parameter]- Iterator over the declared parameter group.
AxoSimPopulation.trainable_adaptation_parameters
axosim.interfaces.AxoSimPopulation.trainable_adaptation_parameters() -> Iterator[nn.Parameter]
Yields only adaptation parameters whose requires_grad flag is true.
Returns
resultIterator[nn.Parameter]- Iterator over the declared parameter group.
AxoSimPopulation.enable_adaptation_training
axosim.interfaces.AxoSimPopulation.enable_adaptation_training(*, behavior: bool=True, morphology: bool=True, synaptic: bool=True) -> None
Freezes shared Lite parameters, then independently enables or freezes behavior_adapter, morphology_adapter, and synaptic_log_efficacy. The defaults enable all three groups.
Parameters
behaviorbool- keyword-only, default=True. Enable gradients on per-neuron behavior rows.
morphologybool- keyword-only, default=True. Enable gradients on morphology-shared adaptation rows.
synapticbool- keyword-only, default=True. Enable gradients on independently mutable contact log efficacies.
Returns
resultNone- No return value.
AxoSimPopulation.enable_full_training
axosim.interfaces.AxoSimPopulation.enable_full_training() -> None
Enable gradients on shared neuron weights and all adaptation parameters.
Enables requires_grad on every module parameter, including shared neuron weights.
Returns
resultNone- No return value.
AxoSimPopulation.synaptic_efficacies
axosim.interfaces.AxoSimPopulation.synaptic_efficacies(synaptic_log_efficacy: torch.Tensor | None=None) -> torch.Tensor
Materialize positive contact multipliers from their log parameters.
Returns exp(log_efficacy) with shape (N,K). Signed contact event amplitudes carry excitation/inhibition; efficacy remains positive.
Parameters
synaptic_log_efficacytorch.Tensor | None- default=None. Optional (N,K) log-efficacy override.
Returns
efficaciestorch.Tensor- Positive multipliers exp(synaptic_log_efficacy), shaped (population, contacts).
AxoSimPopulation.forward
axosim.interfaces.AxoSimPopulation.forward(contact_inputs: torch.Tensor, *, synaptic_log_efficacy: torch.Tensor | None=None) -> torch.Tensor
Predict native spike and soma outputs for the supplied sequence.
contact_inputs is (N,T,K). Optional synaptic_log_efficacy is (N,K) and replaces the stored efficacy values for this call. Return shape is (N,T,2); hidden state starts fresh for the sequence.
Parameters
contact_inputstorch.Tensor- required. Dense signed contact histories; shape defined above.
synaptic_log_efficacytorch.Tensor | None- keyword-only, default=None. Optional (N,K) log-efficacy override.
Returns
predictiontorch.Tensor- Spike-logit and soma-target channels in the tensor shape specified above.
AxoSimPopulation.forward_sparse_contacts
axosim.interfaces.AxoSimPopulation.forward_sparse_contacts(event_summary_indices: torch.Tensor, event_contact_indices: torch.Tensor, event_values: torch.Tensor, *, time_steps: int, synaptic_log_efficacy: torch.Tensor | None=None) -> torch.Tensor
Run exact sparse contact events with full temporal gradients.
The three event tensors are equal-length one-dimensional arrays. Summary indices address nT+t; contact indices address nK+k, and both must identify the same neuron. Integer indices and floating event values must share the module device. Return shape is (N,time_steps,2). Gradients propagate through amplitudes and selected efficacies.
Parameters
event_summary_indicestorch.Tensor- required. Flattened population-time addresses n*time_steps+t, in corresponding event order.
event_contact_indicestorch.Tensor- required. Flattened population-contact addresses n*contacts+k; paired addresses must name the same neuron.
event_valuestorch.Tensor- required. Signed floating-point event amplitudes, one per paired address.
time_stepsint- keyword-only, required. Native sequence horizon.
synaptic_log_efficacytorch.Tensor | None- keyword-only, default=None. Optional (N,K) log-efficacy override.
Returns
predictiontorch.Tensor- Spike-logit and soma-target channels in the tensor shape specified above.
AxoSimPopulation.forward_batch
axosim.interfaces.AxoSimPopulation.forward_batch(contact_inputs: torch.Tensor, *, synaptic_log_efficacy: torch.Tensor | None=None) -> torch.Tensor
Run independent examples through one persistent population.
contact_inputs is (B,N,T,K). Independent examples share population identities and adaptation banks. Return shape is (B,N,T,2).
Parameters
contact_inputstorch.Tensor- required. Dense signed contact histories; shape defined above.
synaptic_log_efficacytorch.Tensor | None- keyword-only, default=None. Optional (N,K) log-efficacy override.
Returns
predictiontorch.Tensor- Spike-logit and soma-target channels in the tensor shape specified above.
AxoSimPopulation.forward_tokens
axosim.interfaces.AxoSimPopulation.forward_tokens(tokens: torch.Tensor) -> torch.Tensor
Run pre-encoded P4 tokens with full temporal gradients.
tokens is (N,blocks,token_dim), already encoded at P4 cadence. Return shape is (N,blocks*4,2). This path decodes supplied tokens directly rather than adding the dense-input path’s initial padding.
Parameters
tokenstorch.Tensor- required. Sequence of encoded P4 tokens.
Returns
predictiontorch.Tensor- Spike-logit and soma-target channels in the tensor shape specified above.
AxoSimPopulation.forward_token_batch
axosim.interfaces.AxoSimPopulation.forward_token_batch(tokens: torch.Tensor) -> torch.Tensor
Run batched pre-encoded P4 tokens with full temporal gradients.
tokens is (B,N,blocks,token_dim). Return shape is (B,N,blocks*4,2).
Parameters
tokenstorch.Tensor- required. Sequence of encoded P4 tokens.
Returns
predictiontorch.Tensor- Spike-logit and soma-target channels in the tensor shape specified above.