> ## 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.
# X3DNA Fiber
> X3DNA Fiber wraps the `fiber` program from the [3DNA/X3DNA](https://x3dna.org/) suite, developed by Xiang-Jun Lu and Wilma K. Olson. From a base sequence it builds an idealized canonical (Arnott) fiber model of a nucleic-acid duplex: A-DNA, B-DNA, Z-DNA, or an A-form RNA duplex, with the complementary strand generated automatically. It is deterministic, CPU-only, and produces three-dimensional atomic coordinates of a regular helix rather than a predicted or energy-minimized structure.
**License:** X3DNA Fiber has a CC-BY-NC-4.0 license and has restrictions around commercial use and may require explicit attribution when utilized. Please refer to [the license](https://x3dna.org/) for full terms. X3DNA is user-provisioned: it is not bundled or auto-downloaded, and must be obtained yourself after free registration at [x3dna.org](https://x3dna.org/). Please cite Lu & Olson (2003, 2008).
Proto is not affiliated with Rutgers University and Columbia University. This toolkit is open source and builds on the implementations produced by these organizations. Product names, logos, and trademarks are the property of their respective owners.
| Function | Description | |
| ------------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `run_x3dna_fiber()` | Build idealized fiber DNA/RNA duplexes from base sequences with X3DNA fiber | Docs Source |
## Background
The `fiber` program in 3DNA ([Lu & Olson, 2003](https://doi.org/10.1093/nar/gkg680); [Lu & Olson, 2008](https://doi.org/10.1038/nprot.2008.104)) constructs regular helices by repeating the canonical geometry of a chosen fiber model along a user-supplied sequence. These geometries are the idealized repeating units derived from fiber-diffraction studies, most of them based on the work of Chandrasekaran & Arnott, that define the canonical [A-DNA](https://en.wikipedia.org/wiki/A-DNA), [B-DNA](https://en.wikipedia.org/wiki/B-DNA), and [Z-DNA](https://en.wikipedia.org/wiki/Z-DNA) conformations, together with an A-form RNA duplex. Each base or base pair is placed according to the fixed helical parameters (rise, twist, and the associated base-pair geometry) of the selected form, so the result is a uniform, sequence-threaded helix.
Because every base step uses the same canonical geometry, the output is an idealized model, not a structure prediction: it does not account for sequence-dependent deformation, flexibility, non-canonical pairing, or solvent and counterion effects, and no energy is computed or minimized. The models are most useful as clean, reproducible starting structures for visualization, as templates for docking or molecular-dynamics setup, or as canonical references against which experimental or predicted structures can be compared.
The 3DNA/X3DNA software was originally developed by Xiang-Jun Lu while in Wilma K. Olson's laboratory at Rutgers University and is maintained by Lu (now at Columbia University) in collaboration with Olson. The distribution is gated behind free registration on the 3DNA Forum at [x3dna.org](https://x3dna.org/).
### Learning Resources
* [X3DNA-DSSR homepage](https://x3dna.org/) (Lu & Olson) - the canonical homepage, forum, downloads, and documentation, including the registration required to obtain the software.
* [3DNA fiber models article](https://x3dna.org/articles/3dna-fiber-models) (Xiang-Jun Lu) - a walkthrough of the `fiber` program, the catalog of canonical fiber models, and the command-line interface.
## Tools
### X3DNA Fiber (`x3dna-fiber`)
Builds an idealized canonical fiber structure from each input base sequence and returns one `Structure` per sequence (the duplex by default, or the sense strand alone), exportable to PDB or mmCIF.
#### API Reference
Source
Nucleotide sequences (5'->3') for one strand of each duplex; the complementary strand is generated automatically. Bases must be A/C/G/T/U (any case). T and U are interconverted to match the requested `form` (T for DNA forms, U for RNA). A single string is normalized to a one-element list.
Source
Canonical helix form to build: `A-DNA`, `B-DNA` (default), `Z-DNA`, or `RNA` (A-form RNA duplex).
Available options: `A-DNA`, `B-DNA`, `Z-DNA`, `RNA`
Output only the single (sense) strand instead of the full duplex (fiber `-single`). Default `False`.
Path to a local X3DNA v2.4 install root (the directory containing `bin/fiber`). Overrides the `X3DNA` environment variable and the resolved tool cache. X3DNA is user-provisioned (CC-BY-NC-4.0); see the tool README.
Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`.
Device to run the tool on.
Maximum execution time in seconds. `None` waits indefinitely.
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
Idealized duplex (or single-strand) structures, one per input sequence, index-aligned with `inputs.sequences`.
Raw structure content in PDB or CIF format.
Format of the content string (auto-detected if omitted).
What the B-factor column represents.
Optional source identifier (filepath or tool name).
Associated metrics (e.g., pLDDT, pTM scores, per-chain lists, pairwise matrices). None values are stripped at construction.
#### Applications
Use this to generate clean canonical helices from a sequence, for example to obtain a B-DNA duplex as a starting model for docking or a molecular-dynamics build, to produce an A-form RNA duplex template, or to create a canonical reference structure to compare against an experimental or predicted model. It is a generator of idealized models rather than a method for predicting the real structure of a given sequence.
#### Usage Tips
* **`form` (default `B-DNA`) selects the canonical model to build.** Choose `A-DNA`, `B-DNA`, `Z-DNA`, or `RNA` (an A-form RNA duplex). `T` and `U` are interconverted automatically to match the form (`T` for the DNA forms, `U` for RNA), so the same sequence can be built in any form without manual editing.
* **`single_stranded` (default `False`) returns only the sense strand.** Leave it `False` to build the full duplex with the auto-generated complement; set it `True` (fiber `-single`) when you need a single strand, such as a single-stranded RNA helix.
* **X3DNA must be installed by you (it is user-provisioned).** X3DNA is not auto-downloaded (it is gated behind free registration at [x3dna.org](https://x3dna.org/) and distributed under CC-BY-NC-4.0). After downloading X3DNA v2.4, place it in the managed cache so `bin/fiber` is found automatically with no environment variable, or point the tool at the install root via the `X3DNA` environment variable (or `PROTO_X3DNA_WEIGHTS_DIR`, or the `x3dna_dir` config field). See [SETUP.md](SETUP.md) for copy-paste steps. Without a resolvable install, the tool cannot run.
## Toolkit Notes
These apply to the X3DNA Fiber tool in this toolkit (`x3dna-fiber`).
* **Runs on CPU and is deterministic.** The `fiber` program is a fast command-line builder with no GPU and no random sampling; the same sequence and `form` always yield the same coordinates. Generation is near-instant for typical sequences.
* **User-provisioned local install only.** X3DNA is gated behind free registration at [x3dna.org](https://x3dna.org/) under CC-BY-NC-4.0 and is not bundled or downloaded automatically. After downloading X3DNA v2.4, place it in the managed cache so `bin/fiber` resolves automatically, or expose it through the `X3DNA` environment variable, `PROTO_X3DNA_WEIGHTS_DIR`, or the `x3dna_dir` config field (see [SETUP.md](SETUP.md)). The tool therefore runs locally with `device='cpu'` and is not available on hosted (`device='proto'`) workers.
* **Produces idealized canonical models, not predictions.** Output is a regular fiber helix with fixed canonical geometry for the chosen form; it does not model sequence-dependent deformation, non-canonical pairing, or energetics. Use a structure-prediction or refinement method when the real conformation of a specific sequence is required.
**Example notebook:** See the [full working example](https://github.com/evo-design/proto-tools/blob/47e34afa5ea240a3b406e323dc38aa5dc85f223e/proto_tools/tools/structure_prediction/x3dna/examples/example.ipynb) for a copy-paste-ready walkthrough.
## Infrastructure Guides
The following guides cover how to run tools efficiently and at scale.
Keep a tool's model warm across calls instead of reloading it every invocation.How GPUs are allocated to tools and how to target specific devices.Fan a batch of inputs out across multiple GPUs.
evo-design/proto-tools/proto\_tools/tools/structure\_prediction/x3dna
Rutgers University
Columbia University
