MD-Find Documentation

Both similarity searches can be combined with metadata filters — the filters then restrict the candidate set that the similarity ranking runs over. The search form has three steps:

1. Upload the main file — the file to search by (optional).
2. Add .tpr file — required for trajectory formats (.xtc, .dcd, .nc), ignored/optional otherwise.
3. Refine with metadata filters — structured filters on ~200 metadata fields (optional).

The Search button is enabled once you have provided a file or at least one metadata filter.

1Search with a static structure (PDB / CIF)

When to use: you have a single conformation — an experimental structure, a model, or one frame exported from a simulation.

How to run

1. Drop your .pdb or .cif file into Step 1 — Upload the main file (or click to browse). Self-contained structure formats are accepted: .pdb, .cif/.mmcif.
2. Leave Step 2 empty — a static structure needs no topology.
3. Optionally add metadata filters (Step 3), e.g. Water Model = tip3p to only compare against simulations of a given setup.
4. Press Search.

What happens behind the scenes

The file is uploaded, an embedding(a fixed-length vector summarising the structure) is computed on the fly, and a nearest-neighbor search looks up the most similar embeddings across all indexed files that pass your filters. This runs as an asynchronous job — the results page shows “Search in progress” until it finishes (typically seconds; you don't need to keep the tab active, the results URL /results/<job-id> is bookmarkable).

2Search with a trajectory (XTC + TPR)

When to use: you want to find simulations whose dynamics/conformational ensemble resembles yours, not just a single structure.

How to run

1. Drop the trajectory file (.xtc) into Step 1.
2. Step 2 is mandatory for trajectories: attach the matching .tpr run file that defines the atoms. Without it the request is rejected with “A coordinates file is required for .xtc/.tpr files.”
3. Optionally add metadata filters — e.g. limit the comparison to one protein (Protein ID), a software version, a temperature range, etc.
4. Press Search.

How the trajectory is treated

The trajectory is embedded with a VAMPnet variant, which captures slow dynamic processes of a MD simulation. Indexed trajectories in the database are created in the same way, so a hit means “some frame of this simulation is close to your query conformation”.

Combining with metadata filters

Filters are applied first — only files matching every filter become candidates — and similarity ranking then runs within that candidate set. Use this to ask sharply-scoped questions such as:

“Find trajectories similar to my query, but only of protein 1AKE, simulated in GROMACS with ensemble temperature between 290 and 310 K.”

Metadata filter syntax

Filters are entered as tokens in the Step 3 search bar. Start typing a field name (or pick it from the suggestion list), choose an operator, enter a value, confirm with Enter. Multiple tokens combine with AND.

Date-valued fields can be given as a range (from–to), which becomes two filters (>= and <=). Number-valued fields can also be given a min–max range (e.g. Ensemble Temperature ≥ 290 and ≤ 310).

Commonly useful fields (there are ~200 in total, auto-completed in the input):

• Protein ID (PDB / UniProt) — the simulated protein(s)
• Title, Creator (ORCID), Identifier (DOI), Publishing Institution (ROR)
• Software, Software Version — the MD package (e.g. GROMACS 2023.1)
• Water Model
• Number of Atoms
• Integrator, Time Step (dt, ps), Ensemble Temperature (K)
• Coulomb Type, Cutoff Scheme
• Simulation File Name

3Metadata-only search (no file)

If you only set metadata filters and upload nothing, the search is synchronous: you are taken straight to a results page titled “Matched by metadata filters”. There is no similarity score — all files that match every filter are returned (up to 100).

4Understanding the results

Similarity results — what the score means

Results from a file search are ranked by structural similarity (subtitle “Ranked by structural similarity”) and every row shows a match badge:

• The backend computes cosine distance between the query embedding and every indexed frame embedding, both unit vectors; range 0 (identical) – 2 (opposite), 1 = orthogonal/unrelated.
• Per result file, the shown distance is the minimum distance across all its frames — i.e. the closest conformation found in that file.
• The UI converts the distance d into a percentage: similarity % = (1 − d/2) × 100 (identical → 100 %, orthogonal → 50 %, opposite → 0 %). The badge is coloured on a red → yellow → green scale and the thin bar under each card shows the same value graphically.
• Hover the badge to see the exact raw cosine distance.

What each result card shows

Results are paginated 10 per page.

Detail panel & 3D viewer

Click a result row to open the detail panel with a Mol* viewer:

• Static structure results (.pdb, .cif, .gro, …) render immediately. You can optionally attach a coordinates file (.xtc/.trr) to play the structure as a trajectory — the attachment is local to your browser session.
• Trajectory results (.xtc, .dcd, .nc, …) need a topology to display: use Attach topology (.pdb, .gro or .cif) and the trajectory plays in the viewer.
• Above the viewer, the dataset info panel lists provenance when available: author, description, DOI (linked), license, keywords, creation/modification dates, download/view/file counts, and a link to the source repository.
• Download and Open source buttons sit in the viewer header.

Note: the attach topology/coordinates feature is a viewer helper for .<ext> files downloaded from the archive — it does not re-run the search.

Empty results / errors

• “No matching files” — no file passed all filters (or no similar file exists); loosen the filters or try a different query file.
• “Search failed” — the job hit an error (the panel shows the message); a common cause is a missing topology for a trajectory upload, or an unreadable file.

5Practical limits & notes

• Result limit: at most 100 matches are returned per search (10 per page).
• One query file per search (plus one .tpr companion).
• Frame stride: trajectories are embedded with an interval of 100 frames, both at index time and at query time.

Supported upload formats in the UI

Drop zones do not validate file extension or size client-side — the backend rejects an incompatible pair at submission time.

6FAQ

Which MD simulation engines are supported?

So far, only GROMACS is supported. We are working on extending support to Amber. Would you like to see more engines included? Let us know.

Can I upload other coordinate files?

Currently, we support only xtc + tpr combinations. However, we are working on extensions to include other formats (e.g., top, gro, itp, etc.). Stay tuned!

7Troubleshooting

I get “Search failed — Embedder service failed: Cannot load the trajectory” — why?

The most likely cause is that the xtc file does not match the tpr file (e.g., wrong number of atoms, the xtc is just a subset, etc.). Ensure both files correspond to the same simulation.