> ## Documentation Index
> Fetch the complete documentation index at: https://proto.evodesign.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Cherimoya

> Cherimoya is a compact sequence-to-function model from the [Programmable Genomics Laboratory](https://github.com/jmschrei/cherimoya) that predicts base-resolution chromatin accessibility from DNA sequence. This toolkit runs the CATv1 collection, one model per ENCODE DNase-seq or ATAC-seq experiment (1,518 experiments, five folds each), and lets you search it, score and profile sequences, and take gradients for design.

![Cherimoya](https://proto-bio.github.io/proto-assets/images/tool/cherimoya/hero.png)[![](https://mintcdn.com/bio-pro/2EYBBzZYWyVjl8bI/assets/images/org-logos/umass-chan-medical-school.png?fit=max\&auto=format\&n=2EYBBzZYWyVjl8bI\&q=85\&s=22969319b0de09508ac3eba8635b3bfa) UCMS](https://proto.evodesign.org/docs/tools/organizations/umass-chan-medical-school.md)

> [!NOTE]
>
> **License:** Cherimoya uses MIT for code and CC-BY-4.0 for model weights and may require explicit attribution when utilized. Please refer to the [code license](https://github.com/jmschrei/cherimoya/blob/main/LICENSE) and [model weights license](https://huggingface.co/programmable-genomics/CATv1/blob/main/LICENSE) for full terms.

Proto is not affiliated with UMass Chan Medical School. This toolkit is open source and builds on the implementation produced by this organization. Product names, logos, and trademarks are the property of their respective owners.

***

 GitHub  70 GitHub  70 ![](https://huggingface.co/front/assets/huggingface_logo-noborder.svg) HuggingFace![](https://huggingface.co/front/assets/huggingface_logo-noborder.svg) HuggingFace  Publication Publication  Cite Cite  Tool Source Tool Source  Open as Notebook Open as Notebook  Open on Proto Open on Proto

![jmschrei/cherimoya](https://opengraph.githubassets.com/1/jmschrei/cherimoya)

 jmschrei/cherimoyaCherimoya is a lightweight sequence-to-function (S2F) model that is small, fast, and easy to use. Now usable by agents. 70 stars

 View repo

[Open](https://github.com/jmschrei/cherimoya)

![programmable-genomics/CATv1](https://cdn-thumbnails.huggingface.co/social-thumbnails/models/programmable-genomics/CATv1.png)

![](https://huggingface.co/front/assets/huggingface_logo-noborder.svg) programmable-genomics/CATv1

![](https://huggingface.co/front/assets/huggingface_logo-noborder.svg) View model

[Open](https://huggingface.co/programmable-genomics/CATv1)

Cherimoya: a lightweight genomic sequence-to-function model built for large-scale design and understandingChristian Ramirez, Achsah Marlene Aruva, ... Jacob SchreiberNature (2026)

 Read paper

[Open](https://doi.org/10.5281/zenodo.21535161)

@miscramirez2026cherimoya\@articleencode2020expanded

```bibtex theme={null}
@misc{ramirez2026cherimoya,
  title={Cherimoya: a lightweight genomic sequence-to-function model built for large-scale design and understanding},
  author={Ramirez, Christian and Aruva, Achsah Marlene and Weng, Zhiping and Schreiber, Jacob},
  howpublished={Genomics x AI Blog},
  year={2026},
  doi={10.5281/zenodo.21535161},
  url={https://genomicsxai.github.io/blogs/2026-011/}
}

@article{encode2020expanded,
  title={Expanded encyclopaedias of DNA elements in the human and mouse genomes},
  author={{ENCODE Project Consortium} and Moore, Jill E. and Purcaro, Michael J. and Pratt, Henry E. and Epstein, Charles B. and Shoresh, Noam and Adrian, Jessika and Kawli, Trupti and Davis, Carrie A. and Dobin, Alexander and others},
  journal={Nature},
  volume={583},
  pages={699--710},
  year={2020},
  doi={10.1038/s41586-020-2493-4},
  url={https://doi.org/10.1038/s41586-020-2493-4}
}
```

 Copy citation

![Proto](https://mintcdn.com/bio-pro/cMLt8hAqaP9M3LKy/assets/logo/logo-light.svg?fit=max\&auto=format\&n=cMLt8hAqaP9M3LKy\&q=85\&s=f5e5dfd1b8f9b9db3a0be0e2eb01f678)

evo-design/proto-tools

 View source

[Open](https://github.com/evo-design/proto-tools/tree/2cb961a77981438592bc527f8469b6b0c18cb98e/proto_tools/tools/sequence_scoring/cherimoya)

Open Notebook

 Open notebook

[Open](https://github.com/evo-design/proto-tools/blob/2cb961a77981438592bc527f8469b6b0c18cb98e/proto_tools/tools/sequence_scoring/cherimoya/examples/example.ipynb)

![Proto](https://mintcdn.com/bio-pro/KVh0EKV-IKblvXR8/assets/logo/evo-logo-light.svg?fit=max\&auto=format\&n=KVh0EKV-IKblvXR8\&q=85\&s=0cb66034ba45618505501aee6ea5f5c1)

[Install MCP](https://proto.evodesign.org/docs/mcp/installation.md)

Toolkit contributors[![](https://avatars.githubusercontent.com/u/3916816?v=4\&s=64)jmschrei](https://github.com/jmschrei)

| Function | Description | |
| - | - | - |
| `run_cherimoya_catalog()` | Search the ENCODE DNase-seq and ATAC-seq experiments a Cherimoya collection has models for | [ Docs](#api-run-cherimoya-catalog) [ Source](https://github.com/evo-design/proto-tools/blob/2cb961a77981438592bc527f8469b6b0c18cb98e/proto_tools/tools/sequence_scoring/cherimoya/cherimoya_catalog.py#L160) |
| `run_cherimoya_gradient()` | Compute differentiable Cherimoya accessibility losses and gradients for relaxed DNA logits (GPU) | [ Docs](#api-run-cherimoya-gradient) [ Source](https://github.com/evo-design/proto-tools/blob/2cb961a77981438592bc527f8469b6b0c18cb98e/proto_tools/tools/sequence_scoring/cherimoya/cherimoya_gradient.py#L366) |
| `run_cherimoya_predict()` | Predict base-resolution DNase-seq or ATAC-seq profiles with Cherimoya (CATv1) models (GPU) | [ Docs](#api-run-cherimoya-predict) [ Source](https://github.com/evo-design/proto-tools/blob/2cb961a77981438592bc527f8469b6b0c18cb98e/proto_tools/tools/sequence_scoring/cherimoya/cherimoya_predict.py#L162) |
| `run_cherimoya_score()` | Predict DNase-seq or ATAC-seq read counts for DNA sequences with Cherimoya (CATv1) models (GPU) | [ Docs](#api-run-cherimoya-score) [ Source](https://github.com/evo-design/proto-tools/blob/2cb961a77981438592bc527f8469b6b0c18cb98e/proto_tools/tools/sequence_scoring/cherimoya/cherimoya_score.py#L145) |

## Background

Cherimoya ([Ramirez et al., 2026](https://doi.org/10.5281/zenodo.21535161)) adapts the BPNet/ChromBPNet architecture into a residual convolutional network of about 614,000 parameters. It takes one-hot DNA of 2,114 bp and predicts two quantities over the central 1,000 bp: a profile head (the shape of the read distribution, one value per base) and a count head (ln of the total reads plus one). Multiplying the softmaxed profile by the expected total gives predicted reads per base.

CATv1 is the Cherimoya Accessibility aTlas, v1: models trained on 1,149 DNase-seq and 369 ATAC-seq experiments from the [ENCODE Project](https://doi.org/10.1038/s41586-020-2493-4), on GRCh38, across 407 biosamples. Each experiment has five models, one per chromosome-held-out cross-validation fold. A model reflects only the assay and biosample of the experiment it was trained on, so pick experiments with `cherimoya-catalog` rather than by cell type name alone.

### Learning Resources

* [Cherimoya: a lightweight genomic sequence-to-function model built for large-scale design and understanding](https://genomicsxai.github.io/blogs/2026-011/) (Genomics x AI) - the announcement post introducing the model, the CATv1 atlas, and the design workflows they are built for.
* [jmschrei/cherimoya](https://github.com/jmschrei/cherimoya) (Programmable Genomics Laboratory) - the reference implementation, with the model code and training scripts.
* [CATv1 model weights](https://huggingface.co/programmable-genomics/CATv1) (Hugging Face) - the released checkpoints this toolkit loads, one per ENCODE experiment and fold.

## Tools

### Cherimoya Catalog (`cherimoya-catalog`)

Searches the experiments in a collection by biosample, assay, biosample classification, accession, and validation performance, and marks one default experiment per (assay, biosample).

#### API Reference

[ Source](https://github.com/evo-design/proto-tools/blob/2cb961a77981438592bc527f8469b6b0c18cb98e/proto_tools/tools/sequence_scoring/cherimoya/cherimoya_catalog.py#L23)

> **Input: CherimoyaCatalogInput**
>
> **biosample** `string`
>
> Case-insensitive regular expression matched against the biosample term name and summary, e.g. `"K562"` or `"hepat|liver"`.
>
> **assay** `string`
>
> Restrict to `"DNase-seq"` or `"ATAC-seq"`.
>
> **biosample\_classification** `array`
>
> Restrict to these ENCODE biosample classifications.
>
> **accessions** `array`
>
> Restrict to these experiment accessions.
>
> **defaults\_only** `boolean` (default: False)
>
> Return only the default experiment of each (assay, biosample), as Chorus committed it. Four of the 492 defaults are experiments ENCODE marks as perturbed; they are returned whatever `include_perturbed` says.
>
> **include\_perturbed** `boolean` (default: False)
>
> Include experiments ENCODE marks as perturbed. Accessions named in `accessions` are always returned.
>
> **min\_count\_pearson** `number`
>
> Minimum fold 0 validation count Pearson.
>
> **limit** `integer` (default: 50)
>
> Maximum number of experiments to return, best count Pearson first.

[ Source](https://github.com/evo-design/proto-tools/blob/2cb961a77981438592bc527f8469b6b0c18cb98e/proto_tools/tools/sequence_scoring/cherimoya/cherimoya_catalog.py#L89)

> **Config: CherimoyaCatalogConfig**
>
> **collection** `string` (default: catv1)
>
> Collection to search.
>
> **verbose** `integer` (default: 0)
>
> Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`.
>
> **device** `string` (default: cpu)
>
> Device to run the tool on.
>
> **timeout** `integer` (default: 3600)
>
> Maximum execution time in seconds. `None` waits indefinitely.
>
> **seed** `integer`
>
> Random seed. When set, tools run reproducibly up to small GPU float noise (see `BaseToolOutput.approx_equal`), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded.

[ Source](https://github.com/evo-design/proto-tools/blob/2cb961a77981438592bc527f8469b6b0c18cb98e/proto_tools/tools/sequence_scoring/cherimoya/cherimoya_catalog.py#L101)

> **Output: CherimoyaCatalogOutput**
>
> **experiments** `List[CherimoyaCatalogEntry]` *required*
>
> Matches, best fold 0 count Pearson first.
>
> **CherimoyaCatalogEntry**
>
> **collection** `string` *required*
>
> Collection the experiment belongs to.
>
> **experiment\_accession** `string` *required*
>
> ENCODE experiment the models were trained on.
>
> **annotation\_accession** `string` *required*
>
> ENCODE ChromBPNet model annotation for the same experiment.
>
> **assay** `string` *required*
>
> `"DNase-seq"` or `"ATAC-seq"`.
>
> **biosample** `string` *required*
>
> ENCODE biosample term name.
>
> **biosample\_term\_id** `string` *required*
>
> Ontology term ID of the biosample.
>
> **biosample\_classification** `string` *required*
>
> ENCODE biosample classification.
>
> **biosample\_summary** `string` *required*
>
> ENCODE biosample summary (donor sex and age, treatment).
>
> **perturbed** `boolean` *required*
>
> Whether ENCODE marks the experiment as perturbed.
>
> **count\_pearson\_fold\_0** `number` *required*
>
> Fold 0 validation Pearson of log total counts.
>
> **profile\_pearson\_fold\_0** `number` *required*
>
> Fold 0 validation Pearson of the base-resolution profile.
>
> **count\_pearson\_mean** `number` *required*
>
> Count Pearson averaged over the five folds.
>
> **profile\_pearson\_mean** `number` *required*
>
> Profile Pearson averaged over the five folds.
>
> **is\_default** `boolean` *required*
>
> Whether this is the default experiment for its (assay, biosample).
>
> **default\_reason** `string` *required*
>
> Why it is the default (Chorus rule); empty when not a default.
>
> **encode\_url** `string` *required*
>
> ENCODE portal page of the experiment.
>
> **n\_matched** `integer` *required*
>
> Matches before `limit` was applied.
>
> **collection** `string` *required*
>
> Collection searched.
>
> **revision** `string` *required*
>
> Hugging Face revision the collection's checkpoints are pinned to.

#### Applications

Use this tool to find which ENCODE experiments have models for a cell type or tissue before scoring, to choose between several experiments of the same biosample, and to look up the assay and biosample behind an accession.

#### Usage Tips

* **The biosample filter is a regular expression.** It is case-insensitive and matches the biosample term name and summary, so `hepat|liver` finds hepatocytes and liver tissue.
* **Defaults come from Chorus.** `is_default` marks the experiment [Chorus](https://github.com/pinellolab/chorus) resolves an (assay, biosample) to: the best fold 0 count Pearson, except 9 pairs pinned to the experiment behind Chorus's ChromBPNet models.
* **Perturbed experiments are hidden from searches by default.** Set `include_perturbed=True` to see the 8 that ENCODE marks as perturbed; named `accessions` and `defaults_only` results are returned either way, and 4 of the defaults (MCF-7, NAMALWA, SK-N-SH and WI38 DNase-seq) are perturbed experiments.

### Cherimoya Score (`cherimoya-score`)

Predicts total accessibility for DNA sequences with one or more models and returns log counts over the 1,000 bp output window, plus expected reads inside a target range when one is given.

#### API Reference

[ Source](https://github.com/evo-design/proto-tools/blob/2cb961a77981438592bc527f8469b6b0c18cb98e/proto_tools/tools/sequence_scoring/cherimoya/shared_data_models.py#L173)

> **Input: CherimoyaSequenceInput**
>
> **sequences** `List[SequenceWindow]` *required*
>
> DNA sequence(s), each with an optional `target_range`; a bare string is accepted. `N` is encoded as all zeros.
>
> **SequenceWindow**
>
> **sequence** `string` *required*
>
> DNA sequence -- an exact model-context window, or a longer source sequence paired with `target_range`.
>
> **target\_range** `SequenceTargetRange`
>
> Optional sequence-relative span the tool must keep inside the model output bins. Windowing is all-or-nothing across a call: set `target_range` on every window or on none (see :func:`windows_target_ranges`).

[ Source](https://github.com/evo-design/proto-tools/blob/2cb961a77981438592bc527f8469b6b0c18cb98e/proto_tools/tools/sequence_scoring/cherimoya/cherimoya_score.py#L33)

> **Config: CherimoyaScoreConfig**
>
> **verbose** `integer` (default: 0)
>
> Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`.
>
> **device** `string` (default: cuda)
>
> Device used for inference.
>
> **timeout** `integer` (default: 3600)
>
> Maximum execution time in seconds. `None` waits indefinitely.
>
> **seed** `integer`
>
> Random seed. When set, tools run reproducibly up to small GPU float noise (see `BaseToolOutput.approx_equal`), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded.
>
> **collection** `string` (default: catv1)
>
> Collection the accessions in `models` come from.
>
> **models** `List[string]` (default: \['ENCSR000EOT'])
>
> ENCODE experiment accessions from the collection, or paths to Cherimoya `.torch` checkpoints with the same 2,114 bp in, 1,000 bp out geometry.
>
> **folds** `List[integer]` (default: \[0])
>
> Folds to load for each accession; several are averaged. A checkpoint path is one model and ignores `folds`.
>
> **reverse\_complement\_average** `boolean` (default: False)
>
> Average forward and reverse-complement predictions.
>
> **batch\_size** `integer` (default: 64)
>
> Sequences per forward pass.

[ Source](https://github.com/evo-design/proto-tools/blob/2cb961a77981438592bc527f8469b6b0c18cb98e/proto_tools/tools/sequence_scoring/cherimoya/cherimoya_score.py#L58)

> **Output: CherimoyaScoreOutput**
>
> **results** `List[CherimoyaScoreResult]` *required*
>
> Per-sequence scores.
>
> **CherimoyaScoreResult**
>
> **scores** `List[CherimoyaScoreMetrics]` *required*
>
> One entry per requested model, in config order.
>
> **sequence** `string` *required*
>
> Input DNA sequence.
>
> **sequence\_length** `integer` *required*
>
> Length of the input sequence.
>
> **context\_start** `integer` *required*
>
> Start of the 2,114 bp model input window.
>
> **context\_end** `integer` *required*
>
> End of the model input window.
>
> **output\_start** `integer` *required*
>
> Start of the 1,000 bp span the model predicts.
>
> **output\_end** `integer` *required*
>
> End of the predicted span.
>
> **target\_start** `integer`
>
> Requested target start, if `target_range` was set.
>
> **target\_end** `integer`
>
> Requested target end, if `target_range` was set.
>
> **models** `List[CherimoyaModelInfo]` *required*
>
> Provenance of each model, in config order.
>
> **CherimoyaModelInfo**
>
> **model** `string` *required*
>
> ENCODE experiment accession, or the checkpoint path for a custom model.
>
> **collection** `string`
>
> Collection of a catalog model; `None` for a checkpoint path.
>
> **revision** `string`
>
> Hugging Face revision the checkpoints were downloaded at.
>
> **assay** `string`
>
> Assay the model was trained on, when known from the catalog.
>
> **biosample** `string`
>
> Biosample the model was trained on, when known from the catalog.
>
> **folds** `List[integer]`
>
> Folds loaded for this model; empty for a checkpoint path.
>
> **checkpoint\_sha256** `List[string]`
>
> SHA-256 of each checkpoint file, in fold order.
>
> **reverse\_complement\_average** `boolean` *required*
>
> Whether strands were averaged.
>
> **Metrics** (one set per `results` item)
>
> | Metric | Type | Range | Availability |
> | - | - | - | - |
> | `log_counts` | float | unbounded | always |
> | `target_counts` | float | unbounded | when target\_range is set |

#### Applications

Use this tool to rank regulatory element designs by predicted DNase-seq or ATAC-seq signal in a chosen biosample, compare a sequence across many cell types at once, or screen candidates before profiling them.

#### Usage Tips

* **Sequences are 2,114 bp windows.** Pass exactly 2,114 bp, or a longer sequence with a `target_range` of at most 1,000 bp and the tool cuts the window.
* **Compare experiments with care.** Raw log counts scale with each experiment's sequencing depth, so the same value means different things in two experiments.
* **Folds and strands are options.** The default runs fold 0; list more `folds` to average them, and set `reverse_complement_average=True` to average both strands.

### Cherimoya Predict (`cherimoya-predict`)

Predicts a base-resolution accessibility profile over the 1,000 bp output window for each sequence and model.

#### API Reference

[ Source](https://github.com/evo-design/proto-tools/blob/2cb961a77981438592bc527f8469b6b0c18cb98e/proto_tools/tools/sequence_scoring/cherimoya/shared_data_models.py#L173)

> **Input: CherimoyaSequenceInput**
>
> **sequences** `List[SequenceWindow]` *required*
>
> DNA sequence(s), each with an optional `target_range`; a bare string is accepted. `N` is encoded as all zeros.
>
> **SequenceWindow**
>
> **sequence** `string` *required*
>
> DNA sequence -- an exact model-context window, or a longer source sequence paired with `target_range`.
>
> **target\_range** `SequenceTargetRange`
>
> Optional sequence-relative span the tool must keep inside the model output bins. Windowing is all-or-nothing across a call: set `target_range` on every window or on none (see :func:`windows_target_ranges`).

[ Source](https://github.com/evo-design/proto-tools/blob/2cb961a77981438592bc527f8469b6b0c18cb98e/proto_tools/tools/sequence_scoring/cherimoya/cherimoya_predict.py#L34)

> **Config: CherimoyaPredictConfig**
>
> **values** `enum` (default: expected\_counts)
>
> `"expected_counts"` returns predicted reads per base; `"probabilities"` returns the profile shape, which sums to 1.
>
> Available options: `expected_counts`, `probabilities`
>
> **verbose** `integer` (default: 0)
>
> Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`.
>
> **device** `string` (default: cuda)
>
> Device used for inference.
>
> **timeout** `integer` (default: 3600)
>
> Maximum execution time in seconds. `None` waits indefinitely.
>
> **seed** `integer`
>
> Random seed. When set, tools run reproducibly up to small GPU float noise (see `BaseToolOutput.approx_equal`), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded.
>
> **collection** `string` (default: catv1)
>
> Collection the accessions in `models` come from.
>
> **models** `List[string]` (default: \['ENCSR000EOT'])
>
> ENCODE experiment accessions from the collection, or paths to Cherimoya `.torch` checkpoints with the same 2,114 bp in, 1,000 bp out geometry.
>
> **folds** `List[integer]` (default: \[0])
>
> Folds to load for each accession; several are averaged. A checkpoint path is one model and ignores `folds`.
>
> **reverse\_complement\_average** `boolean` (default: False)
>
> Average forward and reverse-complement predictions.
>
> **batch\_size** `integer` (default: 64)
>
> Sequences per forward pass.

[ Source](https://github.com/evo-design/proto-tools/blob/2cb961a77981438592bc527f8469b6b0c18cb98e/proto_tools/tools/sequence_scoring/cherimoya/cherimoya_predict.py#L83)

> **Output: CherimoyaPredictOutput**
>
> **results** `List[CherimoyaPredictionResult]` *required*
>
> Per-sequence profiles.
>
> **CherimoyaPredictionResult**
>
> **profiles** `List[CherimoyaProfile]` *required*
>
> One profile per requested model, in config order.
>
> **sequence** `string` *required*
>
> Input DNA sequence.
>
> **sequence\_length** `integer` *required*
>
> Length of the input sequence.
>
> **context\_start** `integer` *required*
>
> Start of the 2,114 bp model input window.
>
> **context\_end** `integer` *required*
>
> End of the model input window.
>
> **output\_start** `integer` *required*
>
> Start of the 1,000 bp span the model predicts.
>
> **output\_end** `integer` *required*
>
> End of the predicted span.
>
> **target\_start** `integer`
>
> Requested target start, if `target_range` was set.
>
> **target\_end** `integer`
>
> Requested target end, if `target_range` was set.
>
> **models** `List[CherimoyaModelInfo]` *required*
>
> Provenance of each model, in config order.
>
> **CherimoyaModelInfo**
>
> **model** `string` *required*
>
> ENCODE experiment accession, or the checkpoint path for a custom model.
>
> **collection** `string`
>
> Collection of a catalog model; `None` for a checkpoint path.
>
> **revision** `string`
>
> Hugging Face revision the checkpoints were downloaded at.
>
> **assay** `string`
>
> Assay the model was trained on, when known from the catalog.
>
> **biosample** `string`
>
> Biosample the model was trained on, when known from the catalog.
>
> **folds** `List[integer]`
>
> Folds loaded for this model; empty for a checkpoint path.
>
> **checkpoint\_sha256** `List[string]`
>
> SHA-256 of each checkpoint file, in fold order.
>
> **values** `string` *required*
>
> What the profile values are (`"expected_counts"` or `"probabilities"`).
>
> **reverse\_complement\_average** `boolean` *required*
>
> Whether strands were averaged.

#### Applications

Use this tool to see where accessibility falls within an element, compare the profile shape between cell types, or plot predicted signal next to measured tracks.

#### Usage Tips

* **Choose the values.** `values="expected_counts"` returns predicted reads per base and `values="probabilities"` returns the profile shape, which sums to 1.
* **Profiles cover the output window only.** Each profile spans `output_start` to `output_end` of the input sequence, the central 1,000 bp of the 2,114 bp context.

### Cherimoya Gradient (`cherimoya-gradient`)

Computes a weighted differentiable accessibility objective over one or more models and, by default, returns its gradient with respect to batched relaxed DNA logits.

#### API Reference

[ Source](https://github.com/evo-design/proto-tools/blob/2cb961a77981438592bc527f8469b6b0c18cb98e/proto_tools/tools/sequence_scoring/cherimoya/cherimoya_gradient.py#L92)

> **Input: CherimoyaGradientInput**
>
> **logits** `List[array]` *required*
>
> Batched relaxed DNA logits with shape `(B, L, 4)` in `A,C,G,T` order, for the designed segment only. Use `B=1` for one candidate.
>
> **temperature** `number` (default: 1.0)
>
> Softmax temperature used to relax logits.

[ Source](https://github.com/evo-design/proto-tools/blob/2cb961a77981438592bc527f8469b6b0c18cb98e/proto_tools/tools/sequence_scoring/cherimoya/cherimoya_gradient.py#L131)

> **Config: CherimoyaGradientConfig**
>
> **collection** `string` (default: catv1)
>
> Collection the accessions in `loss_terms` come from.
>
> **loss\_terms** `List[CherimoyaGradientLossTerm]`
>
> Objective terms summed into one loss.
>
> **CherimoyaGradientLossTerm**
>
> **model** `string` (default: ENCSR000EOT)
>
> ENCODE experiment accession or local `.torch` checkpoint path.
>
> **folds** `List[integer]` (default: \[0])
>
> Folds averaged for this term (ignored for a checkpoint path).
>
> **quantity** `enum` (default: log\_counts)
>
> `"log_counts"`, ln(reads + 1) over the 1,000 bp output window, or `"log_target_counts"`, ln(expected reads + 1) in the config's target span.
>
> Available options: `log_counts`, `log_target_counts`
>
> **direction** `enum` (default: max)
>
> `"max"` minimizes `1 - sigmoid((value - center) / scale)`; `"min"` minimizes `sigmoid((value - center) / scale)`.
>
> Available options: `max`, `min`
>
> **weight** `number` (default: 1.0)
>
> Non-negative scalar applied before terms are summed.
>
> **sigmoid\_center** `number` (default: 4.5)
>
> Value of `quantity` where the sigmoid is 0.5.
>
> **sigmoid\_scale** `number` (default: 1.0)
>
> Positive scale of the sigmoid in `quantity` units.
>
> **context\_left** `string`
>
> Fixed DNA placed before the designed segment.
>
> **context\_right** `string`
>
> Fixed DNA placed after the designed segment.
>
> **target\_start** `integer`
>
> Start of the `log_target_counts` span, relative to the designed segment; `None` means its start.
>
> **target\_end** `integer`
>
> End of the `log_target_counts` span, relative to the designed segment; `None` means its end.
>
> **reverse\_complement\_average** `boolean` (default: False)
>
> Average forward and reverse-complement predictions.
>
> **soft** `number` (default: 1.0)
>
> Blend hard argmax one-hot (0) to softmax probabilities (1).
>
> **hard** `number` (default: 0.0)
>
> Straight-through hard-forward coefficient.
>
> **compute\_gradient** `boolean` (default: True)
>
> Run the backward pass and return the gradient.
>
> **deterministic** `boolean` (default: False)
>
> Use plain PyTorch kernels so repeated gradients are bit-identical.
>
> **verbose** `integer` (default: 0)
>
> Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`.
>
> **device** `string` (default: cuda)
>
> Device used for inference and backpropagation.
>
> **timeout** `integer` (default: 3600)
>
> Maximum execution time in seconds. `None` waits indefinitely.
>
> **seed** `integer`
>
> Random seed. When set, tools run reproducibly up to small GPU float noise (see `BaseToolOutput.approx_equal`), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded.

[ Source](https://github.com/evo-design/proto-tools/blob/2cb961a77981438592bc527f8469b6b0c18cb98e/proto_tools/tools/sequence_scoring/cherimoya/cherimoya_gradient.py#L294)

> **Output: CherimoyaGradientOutput**
>
> **sample\_metrics** `List[CherimoyaGradientSampleMetrics]`
>
> Per-sample loss and term values.
>
> **CherimoyaGradientSampleMetrics**
>
> **loss\_terms** `List[Dict[string, any]]`
>
> Per-term model, quantity value, sigmoid transform, and weighted score for this sample.
>
> **primary\_metric** `string`
>
> Name of the metric that best summarizes the result overall (e.g. `"avg_plddt"` for AlphaFold2). Used by downstream UI and reporting to pick a headline value.
>
> **metric\_type** `string`
>
> Concrete Metrics subclass tag; enables typed reconstruction after a serialization round-trip.
>
> **models** `List[CherimoyaModelInfo]`
>
> Provenance of each model the terms used.
>
> **CherimoyaModelInfo**
>
> **model** `string` *required*
>
> ENCODE experiment accession, or the checkpoint path for a custom model.
>
> **collection** `string`
>
> Collection of a catalog model; `None` for a checkpoint path.
>
> **revision** `string`
>
> Hugging Face revision the checkpoints were downloaded at.
>
> **assay** `string`
>
> Assay the model was trained on, when known from the catalog.
>
> **biosample** `string`
>
> Biosample the model was trained on, when known from the catalog.
>
> **folds** `List[integer]`
>
> Folds loaded for this model; empty for a checkpoint path.
>
> **checkpoint\_sha256** `List[string]`
>
> SHA-256 of each checkpoint file, in fold order.
>
> **gradient** `array`
>
> Gradient matching the input logits, or `None` when `compute_gradient=False`.
>
> **loss** `number` *required*
>
> Sum of per-sample weighted objective values.
>
> **metrics** `Dict[string, any]`
>
> Auxiliary payload from the worker.
>
> **vocab** `List[string]` *required*
>
> DNA column ordering for logits and gradient.
>
> **Metrics**
>
> | Metric | Type | Range | Availability |
> | - | - | - | - |
> | `loss` | float | ≥ 0.0 | always |

#### Applications

Use this tool inside gradient-based DNA design loops, for example to raise accessibility in one biosample while lowering it in others. It is designed for optimizer calls rather than final biological validation.

#### Usage Tips

* **Context fills the window.** `context_left`, the designed logits, and `context_right` must total 2,114 bp; only the designed segment receives a gradient.
* **Set the sigmoid per model.** Both quantities are ln(reads + 1), `log_counts` over the output window and `log_target_counts` over `target_start`..`target_end`, and both depend on each experiment's depth; the default `sigmoid_center` of 4.5 is the median `log_counts` of the default model over hg38 cCREs.
* **Use `deterministic=True` for reproducible gradients.** The default Triton kernels are faster but do not repeat bit-for-bit on GPU.

## Toolkit Notes

These apply to every Cherimoya tool in this toolkit (`cherimoya-catalog`, `cherimoya-score`, `cherimoya-predict`, `cherimoya-gradient`).

* **Models are named by ENCODE experiment accession.** `models` (and each gradient loss term's `model`) takes accessions such as `ENCSR000EOT` (K562 DNase-seq), validated against the bundled catalog.
* **Your own checkpoints work locally.** A path to a Cherimoya `.torch` file with the same 2,114 bp in, 1,000 bp out geometry, no control tracks, and one output can stand in for an accession; remote devices reject paths.
* **Weights download on first use.** Each fold checkpoint (about 2.5 MB) is fetched from Hugging Face at a pinned revision into the managed model cache, and loaded checkpoints stay in the worker between calls.
* **Human GRCh38 only.** Every CATv1 model was trained on human ENCODE data; for another species, any model is a proxy.
* **Runs on CPU or GPU.** A GPU is much faster; on CPU expect tens of sequences per second per model.

> [!TIP]
>
> **Example notebook:** See the [full working example](https://github.com/evo-design/proto-tools/blob/2cb961a77981438592bc527f8469b6b0c18cb98e/proto_tools/tools/sequence_scoring/cherimoya/examples/example.ipynb) for a copy-paste-ready walkthrough.

## Infrastructure Guides

The following guides cover how to run tools efficiently and at scale.

> **[Tool Persistence](https://proto.evodesign.org/docs/tools/guides/tool-persistence.md)**
>
> Keep a tool's model warm across calls instead of reloading it every invocation.

> **[Device Management](https://proto.evodesign.org/docs/tools/guides/device-management.md)**
>
> How GPUs are allocated to tools and how to target specific devices.

> **[Parallel Execution](https://proto.evodesign.org/docs/tools/guides/parallel-execution.md)**
>
> Fan a batch of inputs out across multiple GPUs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.