daicon

Differential Adapters In CONvolutional neural networks.

daicon adds small trainable low-rank residual adapters to frozen PyTorch Conv1d and Linear layers. It was built for finetuning BPNet/Cherimoya-style models to improve differential accessibility, but the core injection API works with explicit module paths in ordinary PyTorch models too.

Installation

daicon is available through PyPI:

pip install daicon

Or, with uv:

uv add daicon

Quickstart

Use explicit module paths for general PyTorch models:

import torch
from daicon import adapter_parameters, inject_adapters

model = torch.nn.Sequential(
    torch.nn.Conv1d(4, 16, kernel_size=7, padding=3),
    torch.nn.ReLU(),
    torch.nn.Conv1d(16, 16, kernel_size=1),
)

config = inject_adapters(
    model,
    targets=["0", "2"],
    architecture=None,
)

optimizer = torch.optim.AdamW(adapter_parameters(model), lr=3e-4)

Use BPNet convenience shorthands when your model exposes BPNet-style fields:

from daicon import inject_adapters

config = inject_adapters(
    accessibility_model,
    targets="rconvs+heads",
)

BPNet shorthand names expand to explicit paths before injection:

Use Cherimoya convenience shorthands when your model exposes Cherimoya-style fields named iconv, blocks, fconv, and linear:

from daicon import inject_adapters

config = inject_adapters(
    cherimoya_model,
    targets="all_postblock",
    architecture="cherimoya",
    block_rank=8,
)

Cherimoya block shorthands wrap whole blocks.* modules instead of replacing the layers inside each block. This keeps the frozen Cheri blocks intact while training small residual adapters around them.

Saving Adapters

Adapters are saved separately from base model weights:

from daicon import count_adapter_parameters, module_specs, save_adapter_bundle

manifest = {
    "adapter_config": config,
    "layer_specs": module_specs(accessibility_model),
    "trainable_params": count_adapter_parameters(accessibility_model),
}

save_adapter_bundle("celltype_f0.adapter.pt", accessibility_model, manifest)

Load them back into a matching base model:

from daicon import load_adapter_bundle

accessibility_model, manifest = load_adapter_bundle(
    accessibility_model,
    "celltype_f0.adapter.pt",
)

By default, bundle helpers expect adapters directly on the module you pass in. This matches the common post-training workflow of loading only a ChromBPNet accessibility module for inference or interpretation.

If you are working with a full ChromBPNet-style object and the adapters live under model.accessibility, pass adapter_root="accessibility":

save_adapter_bundle("celltype_f0.adapter.pt", model, manifest, adapter_root="accessibility")
model, manifest = load_adapter_bundle(
    model,
    "celltype_f0.adapter.pt",
    adapter_root="accessibility",
)

API

The main public functions are:

• inject_adapters(module, targets, ...)
• resolve_adapter_targets(targets, module=None, architecture="bpnet")
• adapter_parameters(module)
• adapter_state_dict(module)
• save_adapter_bundle(path, model, manifest, adapter_root=None)
• load_adapter_bundle(model, adapter_path, adapter_root=None)

Adapter wrappers:

• LowRankConv1dAdapter
• LowRankLinearAdapter
• CheriPostBlockAdapter
• CheriParallelDepthwiseAdapter

Injected adapters compute:

base(x) + scale * up(dropout(down(x)))

The up layer is zero-initialized, so injection is prediction-equivalent to the base model before training. Base layer parameters are frozen inside each adapter. Cherimoya post-block adapters remix frozen block outputs positionwise, while parallel depthwise adapters add a small dilated spatial branch at the block's native dilation.

Artifact Contract

An adapter bundle is a torch.save file containing:

{
    "manifest": {
        "format_version": 1,
        "adapter_config": {...},
        "layer_specs": {...},
        ...
    },
    "state_dict": {...},
}

The state dict contains only adapter branch weights, keyed by injected module path. Frozen base.* weights are intentionally excluded.

Notes

• While the adapters were designed with bpnet-lite and cherimoya in mind, and injection code defaults have been written for these model architectures, daicon is kept intentionally light-weight/general and depends only on PyTorch.
• Conv1d and Linear adapter defaults follow prior ChromBPNet/BPNet tuning: conv_rank=16, linear_rank=4, dropout=0, and alpha-style scaling with alpha=8, i.e. default conv_scale=8 / conv_rank and linear_scale=8 / linear_rank.
• BPNet shorthands assume fields named iconv, rconvs, fconv, and linear.
• Cherimoya shorthands assume fields named iconv, blocks, fconv, and linear; all_postblock is the recommended differential fine-tuning default, with block_rank=8, block_adapter="postblock", and block_scale=1 / block_rank when no explicit scale is provided.
• The historical implementation handoff lives in notes/ADAPTER_HANDOFF.md.