Using StructSub

Your first structure

In the workspace, click Load structure or drop a structure into the viewer. Common formats include CIF, XYZ, extended XYZ, PDB and POSCAR. Use a format carrying a cell and periodicity, such as CIF or extended XYZ, for a periodic framework.

1. Load your file. The viewer draws the atoms, initial bonds and unit cell. Read any connectivity warnings shown after upload.
2. Explore. Drag to rotate about the screen, drag along the edge of the view to roll, scroll to zoom and use Reset to fit the structure back into view.
3. Choose a representation. Ball and stick shows atoms and bonds, with double and triple bonds as two and three sticks and a ring drawn inside each aromatic ring. Orders are assigned when a file is loaded; past 2,000 atoms that would be slow, so use View → Assign bond orders. Space filling shows atomic sizes. Licorice and wireframe emphasise connectivity.

Use StructSub in your browser; no installation is needed. A public local installer and Python package are not available yet.

You can load and view structures without an account, even when your trial editing allowance has run out. The ? links beside tools open the relevant guide section in a new tab.

Import molecular and crystal structure files

The file picker filters for supported filename extensions. For a VASP file named POSCAR or CONTCAR without an extension, drop it into the viewer or add .vasp to its filename. The reader checks the contents when opening a file; an extension alone cannot confirm that it contains a valid structure.

Upload CIF, XYZ, extended XYZ, PDB or POSCAR files to start editing. Supported readers also cover compressed XYZ, ASE trajectories, Gaussian input, DFTB+ geometry, Q-Chem Cartesian input and converged output coordinates, and ADF output coordinate tables. Multi-frame files open at the last frame by default. Through the upload API, supply format for an ambiguous filename and index to choose a frame. Preserve the cell and periodicity when preparing a host for ion or molecular loading.

No file? Build one from a specification

If you have a molecule or a crystal in mind rather than a file, click Build from a specification and describe it in writing. StructSub generates the three-dimensional structure and opens it as a session, exactly as an upload would, so everything else in this guide applies to it unchanged.

You do not need the SMILES. Type a name, trade name, abbreviation, formula or CAS number into Find a molecule (caffeine, H2BDC, CH4, 50-78-2) and pick from the suggestions. Named frameworks appear there too: MOF-5, UiO-66 or HKUST-1 opens the optimised structure directly. A formula usually fits several molecules, so it always gives you a list to choose from.

Build peptides with custom and non-standard amino acids

Residues beyond the twenty. A separated token may name a modified or non-proteinogenic residue: the prefix Me N-methylates its parent (MeLeu, MeVal), the prefix D gives the D enantiomer (DAla), and Sar, Abu, Orn, Nva, Nle and Bmt are known by name. They can be combined: MeDAla is N-methyl-D-alanine, MeBmt the N-methylated Bmt of cyclosporin. An unseparated string stays restricted to the twenty, because it is the FASTA convention and FASTA cannot write any of these.

The wider vocabulary. About ninety residues have names: selenocysteine and pyrrolysine (Sec and Pyl, or U and O when separated); non-proteinogenic residues such as Aib, Hyp, Cit, 2Nal, Phe4F, Tic and aIle; modifications such as Sep, Tpo, Ptr, Kac, Kme3, Rme2a and MetO; and bAla, GABA and Ahx. D gives the enantiomer of any of them (DHyp) and bh the beta-3 homologue (bhVal). Ac, For and pGlu cap the N-terminus, NH2, NHMe and OMe the C-terminus, and H- and -OH may be written for free ends. Anything else goes in braces as SMILES. The full list is served at /monomers.

Building and force-field coverage are separate. A residue remains available to build even when AMBER or CHARMM cannot prepare it. Custom inputs also accept zwitterions, for example Gly-{[NH3+][C@@H](C)C(=O)[O-]}-Gly. Assembly normalises the backbone groups that form peptide bonds while preserving side-chain charges and stereochemistry. When more than one backbone is possible, use a residue SMILES with [*] on the backbone nitrogen and in place of the carboxyl OH. The Relaxation panel names known unsupported residues for the chosen biomolecular model. AMBER additionally supports Hyp in linear, capped and cyclic peptides.

Cyclic backbones must be written, not inferred. A cyclic peptide and the linear one with the same residues are different molecules, and nothing in a list of residues says which was meant - so cyclo(...) is how you ask for the closed one. Putting the two together, cyclosporin A is cyclo(MeBmt-Abu-Sar-MeLeu-Val-MeLeu-Ala-DAla-MeLeu-MeLeu-MeVal).

The two peptide notations overlap, and where a string reads completely as both StructSub asks rather than guesses. ALA is the three-letter code for alanine and a one-letter sequence for Ala-Leu-Ala; both are real peptides, so writing Ala or A-L-A says which you meant. Separate your residues and the question does not arise.

Unseparated text is read one residue per character, as FASTA is. Peptides are capped at 60 residues: the cost of generating a conformer grows roughly with the cube of the chain, so a longer one is a wait rather than a result.

Draw a molecule. In Build a structure → Molecule, choose Draw molecule. Use the same 2D editor as Guests, then choose Use this molecule to fill the SMILES field. Choose Build structure to generate the 3D molecule.

Crystals. Choose Crystal and pick or type the space group, by symbol (Fm-3m, P6_3mc) or number. Only the cell boxes its crystal system needs appear: a for cubic, a and c for tetragonal or hexagonal. Enter each distinct site as an element and fractional x, y and z; fractions such as 1/2 are fine. Under Build, choose a unit cell, a supercell or a sphere or block cluster. A block keeps its far faces, so one cell of rock salt is the 27-atom Na₁₄Cl₁₃ cube. The examples, and the presets under Browse all crystal presets (fcc copper to MoS₂), fill the form. Each atom is bonded to its first coordination shell, and nothing is relaxed. Through the API, send the same crystal as text: {"crystal": "Pm-3m a=3.905; Sr 0 0 0; Ti 1/2 1/2 1/2; O 0 1/2 1/2; sphere 8 at Ti"}.

Graphene, graphite and hexagonal boron nitride

Under Crystal → Browse all crystal presets → Layered materials and 2D sheets, choose graphene (2D sheet) for a carbon monolayer or h-BN (2D sheet) for a monolayer of alternating boron and nitrogen. The graphite and h-BN presets build their stacked bulk crystals.

The sheet presets start with a 4 × 4 in-plane supercell containing 32 atoms, centred in a 20 Å cell height. Change the repeats along a and b to resize the sheet; keep the repeat along c at 1 for a single layer. The c cell length sets the vacuum height. Periodicity → 2D sheet (a, b) keeps bonds periodic in-plane and disables periodicity along c; changing this setting alone does not remove layers from a bulk crystal. These are starting geometries, not relaxed structures.

Through the API, graphene is {"crystal": "P6/mmm a=2.464 c=20; C 1/3 2/3 1/2; pbc 1 1 0; supercell 4 4 1"}. Use extended XYZ or a StructSub project to preserve the two-dimensional periodicity when saving; CIF readers commonly assume three-dimensional periodicity. Ion loading currently requires a three-dimensional periodic host.

Settings are stated, not guessed. Twenty-four space groups have two origin choices, and the same coordinates give different crystals in each. The Origin box appears for those groups; left on Check both, StructSub asks where the two differ and names what each gives. Only a group's standard setting is accepted, so write Pnma rather than Pbnm. A rhombohedral group uses hexagonal axes unless you set Axes to rhombohedral.

From a formula. In the Crystal form, type a composition in the optional Formula box above the space group - the space group and sites are then dimmed and not used, and clearing the formula brings them back. For example NaCl, MgAl2O4, SrTiO3, ZrSiO4, Fe. The formula is matched to a known structure type by its stoichiometry and then by the size of its ions: a radius ratio separates rock salt from caesium chloride, a Goldschmidt tolerance factor separates the perovskites from the ilmenites, and how many d electrons a cation has decides whether it will give up an octahedral site. 37 structure types are matched, and /build/prototypes lists them; /build/candidates?formula=BaTiO3 answers what one composition could be, which is what the buttons below the box are.

What you get is a plausible known structure type with an estimated cell. It is not a measured structure and not a predicted one - predicting a structure from a formula is an unsolved problem, and this does not attempt it. The cell is the type’s own measured cell scaled by the ratio of ionic-radius sums, which lands within a few per cent for an ionic solid and drifts further as the bonding turns covalent or layered. The report that appears when the structure opens names the type, the number that chose it, the oxidation states assumed and anything else taken on trust.

Where more than one type fits, you are asked which. TiO₂ is rutile, anatase and brookite; BaTiO₃ is cubic above 393 K and tetragonal below it; ZnS is wurtzite and zinc blende. All of them are real, so nothing is built until one is chosen - and the choice is offered as buttons under the Formula box, each naming a structure type, the number that would have chosen it and what that type is. Clicking one writes it into the Structure type or symmetry box, so you can also type it yourself: TiO2 rutile, BaTiO3 P4mm or the space group. Where one type is narrower about the chemistry than the others and still fits, it is offered first and marked closest fit - barium titanate's tetragonal form is, being the one it takes at room temperature - but that is an ordering, not a verdict, and where nothing separates the candidates none of them is marked. Ions the wrong size for any type are not a dead end either: the near miss is offered first and can be built anyway. The supercell, sphere and block options a crystal takes follow the formula after a semicolon: NaCl; block 3 3 3.

Solid solutions. Write the fractions and they are worked out: Ba0.5Sr0.5TiO3, La0.7Sr0.3MnO3, Zr0.92Y0.08O1.96. A fraction is not a structure, so the cell is chosen rather than given - the smallest supercell in which every fraction is a whole number of atoms, which is two cells for a half, ten for seven tenths and twenty-five for two twenty-fifths. Vacancies come out of the composition: yttria-stabilised zirconia arrives as Y₈Zr₉₂O₁₉₆, four oxygens short of a full sublattice, because that is what the charges leave. Mixed valence is reported rather than rounded away - the manganese of La_0.7Sr_0.3MnO₃ averages 3.30+. Which site takes which element is a seeded choice that spreads the minority element out: reproducible, and a disordered starting geometry rather than a predicted ordering. Through the API, send {"formula": "La0.7Sr0.3MnO3"}.

Zeolites. Choose Zeolite and type a three-letter framework type code, such as FAU, LTA or CHA; the field suggests the 60 that can be built. The framework is generated from its net: a silicon on every four-connected vertex and an oxygen on every edge, with the geometry fitted to ideal Si–O, O–O and Si–Si distances without lowering the net's symmetry. You get pure SiO₂ in the conventional cell, bonded and not relaxed. Add aluminium, cations or water with the editing tools, and use Relaxation for an optimised geometry. Through the API, send {"zeolite": "LTA; supercell 2 2 2"}; /build/zeolites lists the codes.

Doped zeolites. Choose a framework type, then name what replaces some of the silicon and how much: Si per dopant of 2.5 makes one T atom in 3.5 a dopant. Al, B, Ga and Fe sit on a T site as 3+ and leave a negative charge, so the form asks for a cation to balance it - type any you like (Na, K, Ca2+, Cs), or H for the acid form, which puts a proton on a bridging oxygen next to each dopant. Ti and Ge replace silicon without changing the charge, so they need none. Dopants never share an oxygen (Löwenstein's rule), which sets the densest possible ratio at 1; where an ordering that dense will not fit one cell, as in zeolite A, build a supercell. To study Al–O–Al pairs, turn on Allow Al-O-Al (or add allow Al-O-Al): the sites are then drawn at random, ratios below 1 are allowed, and the summary says how many pairs came out. Cations are placed in the widest parts of the pore, preferring sites near the dopant they balance: a sound starting geometry, not a prediction of where the cations really sit. Through the API this is one string: {"zeolite": "FAU; Si/Al 2.5; cation Na"}.

Zeolites by composition. The ratio can be given as a composition instead, in the optional Composition box under the dopant fields, in whichever way you have it written down: the unit cell as the IZA writes it, |Na58(H2O)240| [Al58Si134O384]-FAU; the batch as a synthesis writes it, Na2O · Al2O3 · 5SiO2; as FAU; a count outright, FAU; Al 58; cation Na; or a loading, CHA; 3 wt% Cu2+ and MFI; 2 mol% Al; cation H. Weight per cent is of the whole structure, framework included, as a supported catalyst is sold; mole per cent is of the tetrahedral sites, as a paper means it. Water is read and not placed - where it sits is a simulation, not a specification. The framework type is still needed: faujasite and several others share a composition, so a formula cannot say which you mean. A clause after the composition may repeat what it says, but not contradict it: |Na58(H2O)240| [Al58Si134O384]-FAU; cation K is refused rather than built with either cation, and so is a loading of one cation followed by cation naming another. A ratio need not land on a whole number of atoms - Si/Al 2.5 over faujasite’s 192 T sites is 54.86 aluminiums - and by default it is rounded and the rounding reported. Choose Smallest cell that makes the ratio exact, or add supercell auto, to get the cell where it comes out exactly instead: seven conventional cells, 384 aluminiums, Si/Al 2.5 on the nose.

The result is a generated conformer: a possible three-dimensional arrangement to use as a starting geometry. It has not been optimised. A generated peptide conformer does not predict its fold. Use Relaxation to optimise the geometry after opening it.

A SMILES string here must describe a whole molecule, with no attachment points. If yours carries a [*] or an R group it is a fragment, and belongs in the Fragment panel instead - see attachment points.

Select and inspect

Picking some copies and not others is how a mixed structure is made. A framework with twenty-four identical linkers can take one substituent on eight of them and a different one on the rest, as two edits: pick the first eight chips, substitute, then pick eight more and substitute again. Each edit leaves the sites it was not aimed at untouched, so a chiral substituent put on half the sites and its mirror image on the other half gives a racemic structure - the handedness of each is the one you asked for, and placement never mirrors a group to make it fit.

Clicks allow small hand movements and near misses within five screen pixels. A larger drag rotates the view or sweeps a selection. Rotation is about the screen, so a sideways drag always spins about the vertical and a vertical drag about the horizontal, however the structure is already turned; a drag that starts along the edge of the view rolls it instead. Atom indices start at 0: the first atom is 0, the second is 1.

Editing shortcuts leave typing and dropdown controls alone. Click the viewer to return keyboard focus to the structure. Deleting atoms is reversible with Undo.

Keyboard shortcuts

Commands (Ctrl/Cmd+K, or ?) lists every command with its keys and runs it, and hovering a control shows its shortcut. On a Mac, Ctrl/Cmd means ⌘ and Alt means ⌥. Single-letter keys wait while you type in a field. Nothing that uses your plan's allowance, such as relaxing or adding hydrogens, has a shortcut.

Growing a selection, and what undoes what

Delete follows the selection type. Explicitly selected bonds are removed together in one undoable edit, keeping their atoms. Selecting atoms makes Delete remove those atoms. Use Select endpoint atoms to intentionally switch a bond selection to atoms. After deleting bonds, the selection clears.

Frame, Hide and Isolate work on the selection. Hiding changes the view only. While atoms are hidden, a Show all button sits at the top of the viewer and beside Hide in the selection bar; U does the same. Use Commands or Ctrl/Cmd+K to search actions and see shortcuts.

Save project downloads a .structsub file with exact coordinates, undo/redo history, experimental datasets, supported settings and every finished calculation listed under Jobs: isotherms, diffusion, migration, mechanics, optimisations and cell refinements, each with its result, its settings and the structure it ran on. Open it from Project & privacy; the calculations come back under Jobs, marked as from the project file, and are not run again. Quick analyses are recomputed after reopening. Structure Export saves geometry in the chosen format, without the project history.

Device recovery is optional and off by default: one browser copy, up to 2 MB, recoverable for 24 hours. Expired copies are removed while this app is open or on the next visit. Forget recovery removes it and disables recovery. Avoid it on shared devices. No server project library or automatic server backup is created. Close & clear session discards temporary session and job results and removes browser recovery; downloaded files remain on your device.

Three different things widen a selection, and they are worth keeping apart because two of them are not reversible by the control that looks like their opposite.

Measuring distances, angles and torsions

Switch to Measure and pick atoms. What you get depends on how many:

Distances use the nearest periodic image, so a bond that crosses a cell boundary measures as a bond rather than as the width of the cell.

Add a bond, including across a cell

1. Choose Edit bonds in Structure tools, or open Edit → Build & clean up → Bonds.
2. Click the first atom and Shift-click the second. The readout shows their distance, relative image and existing bond order.
3. Press Add bond. The view switches to ball and stick so you can see the connection.

Two ways to choose a periodic image

The offset is relative to the first selected atom. Select one atom and a nonzero offset to bond it to its own image. Offsets must use periodic directions. You can connect the same atom pair through different images; an identical connection cannot be added twice.

New bonds start as single bonds. The default force-field preparation assigns chemical orders before optimisation. Adding a bond keeps the atom positions unchanged. Use Undo to remove a mistaken addition.

Change several bond orders, repeatedly

1. Click a bond, then Shift-click to add more. Click a highlighted bond again to remove it. You can also select a group of atoms: the selection bar then shows Bonds (n), which sets the order of, or removes, every bond between those atoms.
2. Use Find similar or Find equivalent to highlight matching groups. Focus a region or an individual match to narrow the edit. Select highlighted keeps those exact bonds as your working selection, which you can adjust with more clicks.
3. Choose Single, Aromatic, Double or Triple under Order. The highlighted bonds change together. A mixed selection shows Mixed.
4. The selection stays highlighted, so you can choose another order immediately. Each batch is one Undo step; Undo and Redo keep the selection when bond identities are unchanged.

The count above the editor tells you how many bonds will change. Search results include bonds inside each highlighted match; bonds connecting separate matches are excluded. Periodic bonds retain their exact image offsets. Clear starts a new selection.

Setting a distance, angle or dihedral

1. Select the atoms in order: two for a distance, three for the angle at the middle one, four for the dihedral about the middle bond. Bonded atoms are put in chain order however you pick them.
2. Press Set distance, Set angle or Set dihedral in the selection bar and type the new value.
3. Choose which side to keep fixed - named by its end atom - or Neither to share the change between both ends.
4. Choose what moves: the attached group (a methyl turns with its carbon) or only the atom. Press Set.

A group move is rigid: every bond inside the moved part keeps its length, and only the coordinate you set changes. Where the two sides are joined some other way - they share a ring, or a framework - there is no separate part to move, so StructSub refuses and suggests only the atom. A move that brings an unbonded atom within 0.7 Å of another is carried out and the close contact named, so you can undo it. Through the API: POST /sessions/{id}/geometry with {"atoms": [0, 1, 2, 3], "value": 60, "move": "last", "part": "group"}, where move is last (keep the first atom’s side), first or both.

Removing a bond, and changing what one is

1. Click a bond in the viewer. Its two atoms become the selection, and the readout names them, their image offset, their distance and the bond’s order.
2. In the bar that appears, press Delete bonds, or open Bond order and choose Single, Aromatic, Double or Triple. The same actions are in the Bonds card. Select two unbonded atoms instead and the bar offers Add bond.

Aim for the middle of the stick. A click is resolved to an atom first and to a bond only when no atom was under the cursor, so clicking close to an atom selects the atom, which is usually the intention. In a dense framework where a bond keeps losing, tick Pick bonds and a bond will win outright. A space-filling view draws no sticks, so ticking the box also switches to ball and stick.

Only the image you clicked is deleted. Two atoms can be bonded through more than one periodic image. Removing all of them because one stick was clicked would take a framework apart, so the others stay.

Changing an order does not move anything. It states what the bond is. The force field types from that, and a force-field deck records it; the geometry follows at the next optimisation. Both actions are ordinary history steps, so Undo brings a deleted bond back with the order it had.

Edit and optimise

Use Build & clean up to add atoms, delete selected atoms, add missing hydrogens, remove unbound guests or clean overlapping atoms from a disordered crystal. To add an atom onto an existing one, select one atom before choosing the new element.

For a fragment edit, select the target sites, choose a compatible fragment from the library or the drawing tools, and use Substitute or Functionalise. Attachment points determine whether a fragment fits the selected site.

Doping: replacing an element

Replace element changes what an atom is without moving it. The position and every bond stay exactly as they were, so the result is the structure you had with a different element at that site. That is substitutional doping. Substitute aluminium for silicon on a zeolite T-site, cobalt for zinc on a metal node, or nitrogen for carbon in a graphitic sheet.

1. Select the atom or atoms to change. Find equivalent turns one pick into every site the symmetry says is the same, so you can dope one crystallographic site and leave the others alone.
2. Open Replace element and choose the new element.
3. Relax afterwards if the new element wants a different bond length. Nothing here moves an atom on its own.

Reopening a fragment in the sketcher

Whatever a fragment came from - the palette, a SMILES string, an uploaded file or a drawing - Edit current fragment puts it back on the drawing canvas. Attachment points come back as R atoms and can be moved, added or removed like any other. A drawing reopens exactly as you arranged it; everything else is laid out in 2D first, because its coordinates are three-dimensional and would otherwise overlap into a tangle.

The button does not appear if the fragment cannot be written as a 2D structure - a metal cluster, for instance - or if this server has no sketcher installed.

Drawing needs a mouse or a trackpad, so it is switched off on phones and on tablets with no pointing device: the canvas expects a pointer that can hover and land within a few pixels, and several toolbar buttons are labelled only by their tooltip. On a touch screen, build the fragment from a SMILES string or upload a file - both reach exactly the same place.

Optimisation after bond editing

1. Finish adding the bonds you need.
2. Open Relaxation. Use auto for the default backend choice, or uff-periodic explicitly.
3. Keep cell optimisation off to refine positions at a fixed lattice. Enable it for a periodic structure when you also want to refine the lattice.
4. Run the calculation, then read its report. Check convergence and warnings before using the result.

The animated process indicator shows the operation and elapsed time. It stays active while background work runs. Reduced-motion settings are respected.

Adsorption isotherms and selectivity

Press Compute isotherm for uptake against pressure, or name a second component for a mixture. Both ends of the curve are computed rather than fitted: the initial slope is Henry’s constant from a Widom insertion integral, and the plateau is the reachable pore volume filled at the guest’s own bulk density. The shape between them comes from the spread of binding energies the pore actually offers, so the strongest sites fill first as they do in a real material.

The report gives the Henry constant in mol/(kg Pa), the isosteric heat of adsorption in kJ/mol, the saturation capacity, the uptake at one bar and the charge and dispersion models behind every number. Export the curve as columns with all of that in the header, or the figure as vector SVG.

With a second component the mixture is solved by ideal adsorbed solution theory (Myers and Prausnitz, 1965), which is what published selectivities are computed with, so a CO₂/CH₄ number from here is comparable with one from the literature. Guest–guest interactions are not included in this estimate, so a curve is sound while the pore is sparsely filled and progressively wrong as it crowds; anything that hydrogen-bonds is wrong throughout, and a strongly polar vapour such as acetonitrile departs from it at a fraction of its vapour pressure (in MOF-5, 60% above the estimate at 1 kPa, and the pores fill by 4 kPa). For those cases, use Simulate.

Simulation (grand canonical Monte Carlo)

Choose Simulate above the button for an isotherm that includes guest–guest interactions and is exact for the force field at every pressure, for one gas or a mixture of two. It runs one simulation per pressure, in parallel, and takes minutes; it uses ten modifications.

Nothing needs to be chosen. Each gas starts at the temperature it is conventionally measured at: nitrogen and krypton at 77 K, argon at 87 K, hydrogen at 77 K, everything else at 298 K. Above its boiling point a gas is swept from 0.01 to 50 bar; below it, as nitrogen at 77 K is, the sweep is in relative pressure P/P₀ from 10⁻⁴ to 0.9, which is how such isotherms are read. Highest pressure in Settings takes a sweep past 50 bar, up to 500 bar, for gas storage (methane is quoted at 65 bar, hydrogen at 100). It never goes past condensation: nitrogen at 77 K ends near 1 bar however high it is set, because there it becomes liquid and there is no gas left to adsorb from; the notes say so, and a higher temperature goes further. Settings also changes the temperature and the Simulation length: Quick for a first look, Standard (the default) for loadings to about 1–2%, Thorough for publication.

Nothing is hidden. Every choice behind a run is in Settings, filled in with its default, and every report repeats the values it ran with. Conditions: temperature, lowest and highest pressure and the number of pressure points (left empty, the sweep uses round steps; set, it is that many log-spaced points, still stopped below condensation). Model: UFF for the framework and TraPPE for the guests, the charges, the mixing rule (geometric, UFF's own, or Lorentz-Berthelot, TraPPE's), the cut-off (12 Å), tapered to zero from 10 Å or cut hard, the energy-grid spacing (0.2 Å) and whether sealed pockets are blocked. Sampling: the equilibration and production cycles that the simulation length stands for, the insertions of the estimate and the random seed. Diffusion: the time step and the equilibration and production times. Change any of them to match another study; Restore defaults puts them all back. The estimate always uses the default model.

Where the molecules sit. The run plays in the view one pressure at a time, with the molecules the simulation left there. Turn on Density beside it to see, instead of one snapshot, where the molecules spent their time at that pressure: a surface around the most visited places, drawn in every cell shown. The slider beside the switch sets the share of the molecules inside the surface, 50% to begin with; lower it to see only the strongest sites, raise it to see the pores they fill. These are the adsorption sites at the temperature and loading simulated, crowding and guest–guest interactions included, which is what Find sites (energy minima of one molecule at 0 K) cannot show. For a mixture the surface is the first gas's.

Each point checks itself: the fugacity recovered from its own sampling must match the one imposed. The (i) says whether every point passed. Cages sealed off from the pore network are excluded, in both methods, because counting guests where they cannot reach overstates the uptake. In pure-silica LTA, for example, it overstates methane’s Henry constant 45-fold.

A drawn or typed molecule works too. The simulation needs its critical temperature, critical pressure and acentric factor; where none are on record they are estimated from the structure (Joback and Lee–Kesler, typically within 3%), the pressures stop at half the estimated vapour pressure, and the (i) says so. If you know the real values, enter all three under Settings. Very small or inorganic molecules cannot be estimated and need the values entered. Flexible molecules are simulated rigid, in one shape.

On the plot, each square is a simulation and each vertical bar its standard error. The line between squares is drawn, not simulated: a monotone curve in log pressure, which passes through every point and never rises or dips between two points unless they do. Read values off the squares, or from the export. At low pressure the simulation and the estimate must agree, since they share the force field; for methane and CO₂ in IRMOF-1 their Henry constants agree within the simulation's error.

Report, under a result, writes it up for a paper. LaTeX folder downloads a zip holding report.tex, references.bib and each figure as a vector PDF (figure1.pdf); the .tex includes the figures and cites the .bib, so a section, a table or a figure can be copied into a manuscript as it is, together with the matching BibTeX entries. Compile it with pdflatex, bibtex, pdflatex, pdflatex. Text is the same report as plain text with numbered references, for a notebook or an email. Both have the same sections: a one-line summary; Computational details, written as a methods section is, with every model, setting and method cited where it is used, taken from the run itself; the results as a table and a figure; a discussion of what the numbers mean (the heat of adsorption, the shape of the isotherm, the selectivity, the diffusivity and, where it applies, the uptake against the targets for natural gas storage, carbon capture or hydrogen storage); the limits of the model for this run; and the references. The discussion is written by fixed rules with their sources cited, never generated, so the same result always reads the same way. Reports are not PDFs by design: they are meant to be edited.

Binding sites. A simulation report also tables the ten strongest distinct places one molecule of each gas binds at zero loading: the energy split into dispersion and electrostatics, the closest contact and which atoms make it, and any hydrogen bond (an H within 2.7 Å of an N, O or F, with the donor-H···acceptor angle at least 120°; C-H donors count). The search covers only the pores the simulation lets the gas into, and scores each site with the simulation’s own force field and charges, so the table explains the low-pressure end of the isotherm. A site repeated by symmetry is listed once, with the number of copies found.

Compare with measurement, under an isotherm, lays a measured isotherm over the calculated one as crosses and says how far apart they are: the mean relative deviation where the two overlap in pressure, and in brackets its sign (negative when the calculation is low). Measured points outside the simulated pressures are drawn but not scored, and points below 2% of the largest measured uptake count only in absolute terms. The file can be an adsorption information file (.aif, as instruments and the NIST database write them), whose units and adsorption branch are read from it, or two columns, pressure then uptake; units named in its header are picked up, and the two menus that appear correct them. Uptake may be in mol/kg (the same as mmol/g), cm³(STP)/g, mg/g or wt%. The measurement stays on the plot for every isotherm shown until you press Remove, so several calculations can be held against one experiment. Nothing is uploaded: the file is read in the browser.

The data export lists every point with its error, both fugacities, the energy drift, the models used and the references to cite. LaTeX table writes a table whose caption cites those references, and BibTeX references writes the matching .bib file. The method was checked against an independent reference implementation on identical force fields (methane and CO₂ in IRMOF-1, and their mixture).

Flexible frameworks (breathing and gate opening)

By default a simulation holds the framework Rigid, so it cannot show a framework that changes shape as it fills, the way MIL-53 closes on CO₂ and opens again at higher pressure. Under Simulate, choose Flexible and press the button: nothing else is needed. The framework is squeezed in steps, and at each step its atoms and cell shape relax, so the compression goes into its softest motion. For MIL-53 that is the hinge that closes the pore, found without being told. Two forms are kept, at 86% and 72% of the volume, and the simulation runs on all three. They are compared by the osmotic framework adsorbed solution theory (OFAST; Coudert et al., 2008): at each pressure the framework takes the form with the lowest osmotic potential. The squeezing uses MACE-MP-0b3 with D3 dispersion when it is installed and the cell is small, which puts MIL-53's cell within 1% of experiment, and UFF4MOF otherwise. It uses thirty modifications. If you have the other form as a structure, Other form uses it instead.

The run plays in the view as a simulation does, one frame per pressure, but the framework changes with it: at each pressure it is drawn in the form it takes there, holding the molecules simulated in that form, so MIL-53 can be watched closing on CO₂ and opening again. With hysteresis the frames go up the adsorption branch and back down the desorption one; the label under the slider names the form and the direction. Hide puts the structure back as it was.

Where the steps fall depends on one number no model gets right: the free energy between the empty forms, per mole of formula units. Force fields and learned potentials miss it for MIL-53 by tens of kJ/mol, in opposite directions, where a few decide the answer. So nothing is guessed. Left empty, the forms are taken as equally stable, and the result is labelled so. What it then shows is which form adsorption alone favours at each pressure. Under Settings, enter the difference if you have it from the literature or a calculation (for generated forms, of the most closed one; the one between takes a share by volume), or enter a Measured step up and it is fitted to match. With an uploaded other form, a Measured step down fits the hysteresis too.

Real breathing is hysteretic. Hysteresis keeps the framework in its current form until another is lower by that much, which opens a loop between the adsorption and desorption branches. It is a model of the barrier, not a prediction of it; zero gives the equilibrium steps. The export has every form's potential and cell, both branches, the steps with their uncertainty, the model's energies for the record, the difference each pressure would need for a step, and every simulated point, so the result can be recomputed with another free energy without simulating again.

Diffusion

Diffusion follows the molecules in time. Give the pressure (it sets how many molecules are in the pores) and press Run diffusion. The simulation first fills the framework at that pressure, exactly as an isotherm point does, then moves the molecules as rigid bodies under the same force field (the framework is held rigid) and records how far each travels. Several independent trajectories run at once, one per processor core, each from its own snapshot of the filled framework; their results are pooled, and the spread between them is the error. Temperature, run length (Quick 100 ps, Standard 500 ps, Thorough 2 ns) and charges come from Settings, and a second gas makes it a mixture, as for the isotherm. It uses ten modifications.

You get three numbers. The self diffusivity is how fast a single molecule wanders. The transport diffusivity is what sets how fast a crystal fills or how much passes through a membrane; it is the collective diffusivity times the thermodynamic factor, Darken's relation, and the factor comes from the loading fluctuations of the simulation that set the loading. At low loading the factor is 1 and the two diffusivities agree; as the pores fill they part. The plot is the mean squared displacement against time: a straight line means the molecules are diffusing, and the diffusivity is its slope over six.

Each run checks itself. The temperature is held by a stochastic thermostat that does not disturb diffusion, the energy it exchanges is booked so the total is conserved, and the (i) gives that drift, which should be near zero, and the temperatures of translation and rotation, which should agree. If the displacement has not yet become a straight line where it is fitted (molecules still rattling in their cages), the notes say so; run longer. Methane in IRMOF-1 at 298 K, at the same loading, matches an independent reference implementation on the same model: 3.14 ± 0.04 against 3.02 ± 0.09 × 10⁻⁸ m²/s over ten reference runs. For CO₂ the reference could not hold its temperature (rotation and translation drifted from 250 to 360 K between runs), so no comparison is quoted; here both stay at 298 K. If a molecule is driven into the framework by too long a step, the trajectory goes back to its last checkpoint, at most 2 ps earlier, and carries on at half the step; the notes say so. Molecules that squeeze through windows narrower than themselves diffuse too slowly for a short run to see; for those the result will say it is not yet diffusive. Continue the run, or use cage hopping below.

Continuing a run. A finished run keeps where every trajectory stopped. Continue run under the result carries the same trajectories on for the Production length in Settings, with no new filling and no new equilibration, and fits the diffusivity to the whole run. Do it as often as needed: a run stopped at the time limit for one calculation keeps what it sampled and continues from there, so a slow guest can be followed for nanoseconds in parts. The state point, charges and model are the first run's. A continued run is the same trajectory one long run would have been, step for step. It is charged like a run of the added length. The saved state travels in project files, so a run can be continued after its result has left the server; open the project and press Show on the run first, so the view holds the structure it ran on.

Cage hopping (dcTST). When molecules leave a cage rarely, as propylene does through narrow windows, choose Cage hopping (dcTST) instead of molecular dynamics. It works out the free energy of one molecule across the cell, averaged over its orientations, from the same force field: the wells are cages and the peaks are the windows between them. The rate over the highest peak, corrected by short trajectories started on it for molecules that cross and bounce back (the transmission coefficient κ), gives the diffusivity along each direction, and their average is comparable with the molecular dynamics value. It takes seconds to minutes rather than hours, and the plot shows the profile so the barrier can be read off. It is for one molecule in the empty framework, the low-loading limit; at high pressure, where molecules share the cages, molecular dynamics at the loading is the measure. For methane in LTA at 298 K it gives 1.48 × 10⁻⁹ m²/s against 1.39 ± 0.10 × 10⁻⁹ from a 2 ns molecular dynamics run at 0.6 mol/kg on the same model. It uses ten modifications.

Watching it. When a diffusion run finishes, its molecules play over the framework in the view, and Play, the slider and the speed (down to 0.01×) step through the run; Loop starts it again at the end. Paths draws the route each molecule has taken so far, which shows the channels and cages they actually use. A simulated isotherm does the same one pressure at a time, so you can watch the pores fill, and its curve on the plot grows point by point with them, the pressure on show ringed. The simulation box is usually several cells, so the view draws as many; Hide takes the molecules out and Show puts them back. Nothing is added to the structure. Earlier results on the same structure stay in the Result menu at the top of the panel, so a diffusion run does not replace the isotherm before it.

Breakthrough

Breakthrough predicts what a breakthrough experiment measures: a packed column of the framework, fed with a gas mixture, and the composition leaving it over time. Choose the gas at the top of the panel and, under Isotherm, the gas it competes with and its share (CO₂ against N₂ at 15% is the usual flue-gas test); give the total pressure and press Run breakthrough. A single gas is fed in helium. Each gas's isotherm is simulated by GCMC at the column's temperature over the pressures the column will see and fitted, the mixture's uptake is predicted from the fits by ideal adsorbed solution theory, and the gas is then followed through the bed. It uses twenty modifications.

The plot is each gas's outlet concentration over its feed against time. The weaker gas breaks through first and often leaves above its feed for a while (roll-up), pushed off the crystals by the stronger one arriving behind it; the time between the two breakthroughs is how long the column separates them. The table gives each breakthrough time, the uptake at the feed, the selectivity, the mass balance and the grid.

Nothing needs setting. The column under Settings → Column is a laboratory one (0.3 m, 40% voids, 0.1 m/s, the framework's own density) and every value is shown, so it can be matched to an experiment. By default the crystals take the gas up at local equilibrium, so the curves show what the isotherms allow; enter a mass transfer coefficient (15 D / r², with D from Diffusion and r the crystal radius) for kinetics. The column is solved again on half as many grid cells and refined until breakthrough times move by under 0.5% and peaks by under 0.01 of the feed; the table says how much they moved. The Data button also offers the same column as an input file for the reference breakthrough code, so the curve can be reproduced independently.

On the reference code's own examples (CO₂/propane in MOR, seven C₇ alkanes in BEA with a pressure drop) the breakthrough times agree to within 0.1%, and to 0.015% for most gases, once the reference is taken to a fine grid. The model is isothermal: a strongly adsorbing gas such as CO₂ warms the bed, which moves real breakthrough curves, and that heat is not included.

Membrane

Membrane predicts how a gas crosses a membrane made of one crystal of the framework. Choose the gas at the top of the panel and, under Isotherm, the gas it competes with and its share; give the feed and permeate pressures and press Run membrane. Two models are offered: Pure gases (fast), the default, for screening, and Mixture (Maxwell-Stefan) for the real mixture.

Mixture (Maxwell-Stefan): each gas's isotherm is simulated by GCMC and fitted against fugacity. The mixture is then simulated at several loadings between the feed and the permeate (four by default): GCMC sets each loading, and molecular dynamics measures how each gas moves and how strongly the gases drag on each other (the Onsager matrix, cross terms included). The membrane is solved for the steady fluxes, which are the same at every depth. The result gives each gas's permeance (GPU), permeability (Barrer) and flux, the permeate composition, the separation factor and the permeation selectivity. The selectivity is split into what adsorption contributes and what diffusion contributes, and the coupling between the gases is shown by solving the same membrane without it. The plot shows the loading, fugacity, chemical potential or diffusivity through the membrane, or permeance and selectivity against feed pressure.

Pure gases (fast) simulates each gas alone: its isotherm and its corrected diffusivity at low loading. It gives each gas's permeability in the Henry limit and at the stated pressures, and the ideal selectivity, which is a ratio of pure-gas permeabilities and not a mixed-gas separation factor: in a mixture the gases compete for sites and drag on each other, and the ranking can change.

The transport coefficient is always the corrected (collective) diffusivity from the summed motion of the molecules, never the self-diffusivity. The two agree only at zero loading. The solver checks itself: it solves on two grids and estimates the error, solves again independently by collocation, and checks that the flux is the same at every depth. It refuses the result if these disagree by more than 0.2%. It also refuses when the simulated loadings do not cover the membrane, and asks for more of them rather than extrapolating. At each simulated loading, ideal adsorbed solution theory is compared with the mixture simulation, and the result says where they disagree.

Settings → Membrane holds the thickness (1 µm), the orientation and the permeate. The average over directions is exact for a cubic crystal; for others, choose the plane the membrane faces, and Plane shows it in the view. With no sweep gas, the permeate is whatever crosses the membrane. Finished diffusion runs of the same mixture and temperature can be reused instead of new loadings. The pure-gas model costs ten modifications per gas; the mixture model costs ten for each loading plus ten.

Loading: molecules and ions

On StructSub Cloud, Loading is part of a paid subscription: filling structures with molecules or ions, binding sites, custom guests, isotherms (estimate and simulation), mixture selectivity, flexible frameworks, diffusion, breakthrough, membranes and ion migration. Without an account you are asked to sign in first. Remove guests is open to everyone.

Choose Molecules in the Loading tab for molecular loading and adsorption. Fill structure places guest molecules throughout the structure to a loading you choose; Find sites puts a single guest in thousands of trial positions and orientations and ranks the candidate sites using the stated molecular interaction model. This ranking does not predict battery insertion energies or redox stability. Use Remove guests in Loading or Edit → Clean up to remove unbound guest molecules. The first is an edit and goes on the undo stack. The second changes nothing until you press Place in site 1.

Ion insertion and extraction in MOFs, COFs and periodic crystals

Choose Ions, an element and Insert or Extract. Count is the number of atoms to add or remove and works with MOFs and COFs without entering a framework formula. Final formula is optional and includes the whole host; Li0.4S requests 0.4 Li per S. The builder expands the cell when needed to obtain exact integer counts and preserves the ratios of all other elements. For complete extraction, use Li0S or the host-only formula S.

Best sites first ranks sampled insertion sites with UFF dispersion/repulsion and damped, shifted Coulomb electrostatics (12 Å cutoff). Set the ion model charge; Auto uses current imported host charges, then a trained model when available, otherwise QEq. Each insertion updates the remaining scores for interactions with ions already placed. Alternatives start at different sites, and completed configurations are sorted by score. Choose a configuration to inspect its formula and 3D preview, then Apply configuration to make an undoable edit. Export the applied structure normally. The configurations stay available after applying: preview another and apply it to replace the current configuration. Each switch is undoable, and the applied configuration is labelled. Editing the structure elsewhere or generating a new search requires a fresh set of configurations. Settings control the number of configurations, minimum insertion distance and random seed. Fewer configurations may be returned when the choices are exhausted.

The result (i) records the charge model and score components. Scores compare configurations only within one search and omit constant ion self-image terms. Best means lowest found in the sampled sites under this fixed-host model; generic UFF ion parameters are not a validated battery potential. No counterions, compensating electrons, charge transfer, solvent response, stable phases or battery performance are predicted. Spacing only and extraction make geometric candidates. Source charge assignments are cleared because the composition changes. Use an appropriate validated model before calculating energies or relaxing. Molecular site-search energies do not describe battery insertion. This workflow currently requires a three-dimensional periodic host, with limits of 5,000 atoms and 100 repeated cells.

What a loading percentage means

100% is the guest’s own bulk liquid density filling the pore volume a guest can actually reach. So 50% water is half of liquid water’s density in that volume, not half of some undefined maximum. The readout always gives the density in g/cm³ next to the percentage, along with weight per cent and mmol/g, because a percentage of an unstated quantity is not a number anybody can check. The menu states, for each guest, which density it is using and the state that density was measured in - liquid nitrogen at 77 K is a different thing from nitrogen gas.

If the pore is too cramped to hold liquid density, you get the geometric packing limit instead and the report says so.

Choosing the guest, and how much of it

Species is one box. Click it for the guests with a force field published for that molecule and measured critical constants, which both methods compute as published: water, CO₂, SO₂, N₂, O₂, H₂ and the noble gases, and every catalogued molecule made of groups TraPPE covers (alkanes, alkenes, aromatics, alcohols, ethers, ketones, aldehydes and nitriles), filed by family; then every other catalogued gas on a generic model. Or type: a name (suggestions appear as you type, from about a thousand compounds with their constants), a formula such as SO₂ or C₂H₆O (in any order, and lower case works), a SMILES string or peptide: GAV for a peptide. Draw beside it sketches one. Those run on estimates, and the note under the menu says which: generic UFF parameters and computed charges for the force field; critical constants from the literature where we hold them, otherwise from the structure; and a liquid density measured, or estimated from the structure or, failing that, from the molecule's volume. The same holds for the second gas of a mixture. Pick a catalogued molecule, type a SMILES string or press Draw and sketch one. A drawn guest is the whole molecule - unlike a fragment, it bonds to nothing, so it needs no attachment points. What you drew is turned into SMILES and its formula is shown before anything is run, which is where a drawing that became the wrong molecule announces itself.

Amount is a percentage of a full load, an exact count or an absolute density to fill to. A count is how you ask for a single molecule, when what you want is one guest in the strongest site rather than a filled pore. A density is an absolute target and needs nothing known about the molecule at all.

Where the density comes from

A percentage is a percentage of the guest’s bulk liquid density, so that number has to come from somewhere, and the readout always says which of three places. The 77 catalogued molecules carry a density somebody measured. Anything else gets an estimate, from group contributions and the Rackett equation - checked against those 77 measurements, where it is typically 4% out and never worse than 18%.

Where the estimate is known to fail it is refused rather than quietly returned: anything that hydrogen-bonds, because the method puts water six times too dense; anything with fewer than three heavy atoms, because hydrogen comes out thirty-four times too dense; anything without a carbon–hydrogen bond; and sulfoxides, which the method has no group for. A refusal points at the count and the density, neither of which needs anything estimated.

A drawing is matched against the catalogue by structure, not by name, so sketching water gets the measured density and the published TIP3P model however you drew it.

Looking at the result, and keeping it

Once guests are placed the view frames the whole complex, host and guests together. Reset (or Shift+F) does it again after you have moved the camera, and Download saves the complex in the format chosen in Export.

Reachable, and sealed

A cavity a guest could never travel into holds nothing, however large it is. In a crystal, reachable space is the part that joins up with its own image across the cell boundary - a channel running through the material rather than a pocket that happens to be roomy. In a finite structure it is the part joined to the outside. Sealed cavities are measured, reported and left empty; Fill sealed cavities fills them too, which is right for solvent templated in during growth and wrong for anything you mean to compare with an adsorption measurement.

How sites are chosen

Guests do not go in at random. Every candidate position is scored by the interaction energy a guest would have there, and the strongest sites fill first - which is what happens in a real adsorption, and why a light loading reports a better mean energy than a heavy one. Each site is tried in many orientations; a rigid molecule has three rotational degrees of freedom and dropping it in facing one way is not a search.

Find sites goes further: it refines the best candidates as rigid bodies over all six degrees of freedom before ranking them, then collapses poses that converged on the same place, so a list of five sites is five places and not one place found five times. Each energy is split into its dispersion and electrostatic parts. In a symmetric framework the top sites often come back with identical energies; that means symmetry has repeated one site, not that the framework has five different ones, and the report says so.

Charges, and what they are worth

Energies are UFF dispersion plus electrostatics. The electrostatic part needs charges on the host, and where they come from is reported with every number they influenced:

What it is not

This is a packing and a pose search, not a simulation. Guests are rigid and placed in their gas-phase geometry; guest–guest energies are not optimised, only their overlaps prevented. Switch on Relax guests afterwards to settle them with the framework held fixed, which is what turns a placement into a structure worth quoting. A loading is a plausible starting configuration for a calculation, not a predicted adsorption isotherm.

Attachment points: telling us where a fragment bonds

A fragment on its own is just a molecule. What makes it substitutable is knowing which of its atoms take the place of the bonds you are cutting - those are its attachment points.

Mark one atom per bond the fragment must make:

All three mean the same thing. The count is what matters: a terminal group such as –OH needs one mark, and a linker that bridges two sites needs two, one at each end. Marking too few leaves a bond with nothing to attach to, and the substitution is refused rather than guessed at.

Analyse, export and preserve bonding

Choose an analysis in Analyse. Compare results before and after an edit to check how the structure has changed.

You can run all analyses together or select individual ones. If an analysis is unavailable, the report explains why and the others continue. Selecting only what you need avoids unnecessary calculations.

Click Export to download the current structure in your chosen format. Downloads require a signed-in account. Export is next to Load structure at the top of the sidebar.

Export as…, below it, holds everything else. Structure file lists every format the structure can be written in, about forty: coordinate and crystal files (CIF, XYZ, extended XYZ, PDB, MOL, SDF, XSF, SHELX and more), periodic DFT inputs (VASP, FHI-aims, CASTEP, ABINIT, Elk, CRYSTAL, WIEN2k, ONETEP, DFTB+, CP2K, Quantum ESPRESSO and more), molecular quantum chemistry inputs (Gaussian, ORCA, Q-Chem, NWChem, GAMESS, TURBOMOLE), molecular dynamics files (LAMMPS, GROMACS, GROMOS, DL_POLY) and the bond-carrying force-field deck. The menu names each program. A format that does not suit the structure is greyed with the reason: VASP needs a cell, ORCA and Q-Chem take molecules. The program inputs written here carry exact coordinates, cell and charge, with a stated default method to review before running.

Picture saves the view as a PNG up to 8192 pixels across, drawn again at that size rather than enlarged, on white by default, on a studio backdrop, on any colour you pick or on a transparent background for a figure. Movie records an MP4 (WebM in browsers that cannot make MP4): either the molecules' run from a diffusion or an isotherm simulation, or a full turn of the structure. Trajectory writes that run as a multi-frame Extended XYZ, XYZ or PDB file, with the framework repeated to fill the simulation box and the time or pressure of each frame, for analysis in other software. All of them show the structure as it is on screen, from where you are looking. A picture can have the plot on show placed beside the structure, and a movie of a simulated isotherm can have the curve growing beside the molecules; both are off unless you switch them on.

Force-field decks

The force-field deck formats write a UFF4MOF input that carries the bond orders, which is the whole reason to use them: a coordinate file has nowhere to put connectivity, so a deck states it and the force field is typed from what you actually edited. Two are offered because they answer different questions.

A molecule has no lattice, so it is always written fixed-cell. If these options are not listed, this server does not have the optional atom-typing package they need.

Projects

Save project downloads a .structsub file with the structure, its full undo history, exact bond graph, every loaded pXRD pattern and your finished calculations. Open project restores it into a new session, with the calculations under Jobs. Project files stay on your device; the server keeps nothing after the session ends, including the calculations a project brought in.

Keep recovery on this device stores one browser copy, up to 2 MB, for 24 hours. Leave it off on shared computers.

Design a framework from its building units

Everything above edits a structure you already have. The Framework panel goes the other way: give it the pieces - a metal node, a linker - and it works out which periodic nets they can form, then assembles one. This is reticular synthesis on paper, done in software.

1. Add your building units

Type a SMILES string, or drop a structure file. You can also click Use the open structure as a unit to take whatever is currently in the workspace.

Each unit is read as soon as it arrives, and StructSub reports what it found: how many connection points, at what angles and whether they were given or inferred.

Once a node is in the set, each inferred linker is joined to suit it. A nitrogen bonds along its lone pair, about 2.08 Å from the metal, and an azole loses its N-H hydrogen. A carboxylate joins at the ring carbon when the node already carries the carboxylates, and through one oxygen when the node is a bare metal; choose Both O to bridge. A sulfinate or dithiocarboxylate joins the same way, and a sulfonate or phosphonate through one hydroxyl oxygen. None of those can join a node that carries carboxylates, and the unit says so.

Two linkers can share a net when they bond to different sites of the node. A paddlewheel with six connection points, four on carboxylate carbons and two on its metals, takes terephthalic acid on the first and DABCO on the second, and pcu comes out as DMOF-1 with BDC in the layers and DABCO between them. Two linkers that bond to the same kind of site are refused, because nothing says which edge each one takes.

For the metal node, open Metal SBU library. It holds nodes cut from optimised frameworks, connection points already marked, with the most used first; filter by metal or by number of connection points and click one to add it. Each row is named by its formula (Zn₄O(CO₂)₆, Cu₂(CO₂)₄, Zr₆O₈(CO₂)₁₂), with the motif where one is recognised, its connectivity and shape and how many structures contain it. Draw only the linker.

A node the library does not have can come from your own structure. Open a framework that contains it, run Deconstruct and click Use in builder on the node. It is added with its connection points marked, exactly as a library node is.

A node with one metal can be drawn or typed as SMILES, for example *[Cu](*)(*)(*)(*)* for an octahedral copper with six connection points. Each ligand is built on its own, then placed on the vertices of an ideal polyhedron at metal–ligand lengths measured across the SBU library. A chelate such as acac or bipyridine is fitted onto vertices its bite can reach, and a porphyrin picks square planar by itself. A cluster with more than one metal cannot be drawn: its shape cannot be worked out from a drawing, so take it from the library or cut it from a framework.

The box at the top of the Metal SBU library also takes a motif (paddlewheel, Zn4O, Zr6, oxo trimer, Cu2I2, cubane; small typos are forgiven and the line under the box says what it was read as) or a named framework (HKUST-1, UiO-66, MOF-5), which shows the SBU that framework is built from. Motifs are recognised from each unit’s own atoms and bonds. Where a framework’s node is not in the library, the nearest ones with the same motif and metal are shown and the line says so.

If you know the metal salt rather than the SBU, type it into the box at the top of the Metal SBU library: a name (zinc nitrate hexahydrate, ferric chloride, uranyl acetate) or a formula (Cu(OAc)2·H2O, ZrOCl2·8H2O). The library is reordered by how often each SBU occurred in published MOFs made from that salt, and the number on each row is that count. This is a record of what happened, not a prediction: the SBU also depends on the linker, the solvent and the temperature. A salt never recorded falls back to all salts of its metal, and a metal never recorded to its closest analogue (zirconium for hafnium, a neighbouring lanthanide for a lanthanide); the line under the box says which. Linkers sold as sodium salts, and anything without a metal, are refused.

A single complex can also be typed the way it is written on paper: Cu(H2O)6, Cu(NH3)4(H2O)2, Co(acac)3, Ru(bpy)3 or Cu(*)4(H2O)2 for a node whose * are connection points. It works in the SMILES box here and in Build structure. Like ligands take the most symmetric sites, so the two waters in Cu(*)4(H2O)2 are trans.

Any unit with a metal has small menus beside it.

Both are starting geometries. Either change can be set back, because the unit is always rebuilt from where it came from.

An acid linker can meet its node in more than one way, and the node decides which is right. Each such linker has a small menu; Auto picks for you and shows its choice.

Click edit to open a unit in the workspace, where every tool in this guide applies to it: delete a stray solvent, add the hydrogens, replace an element. When you are done, Use the open structure as a unit puts it back in the list.

2. Find the topologies that fit

Find compatible topologies searches the RCSR library for nets that match your units’ connection counts, then ranks them by how closely the connection angles fit.

Use Topology dimensions to choose 2D sheets, 3D frameworks or both. The combined view keeps up to 12 candidates from each dimension, so higher-ranking 3D nets cannot hide all the sheets. A three-connected unit can fill the vertices of a honeycomb (hcb) sheet by itself; its geometry still determines the fit and whether the generated bonds close satisfactorily.

At least one unit must have three or more connection points to fill the vertices of a net. A two-connected linker spans an edge between vertices. In MOF-5, for example, Zn₄O clusters occupy the vertices of pcu and terephthalate linkers connect them.

These verdicts compare angles only. They cannot see how far a unit reaches or whether atoms collide, so a compatible net can still fail to close - the build report says whether it did.

If you already know the net, type its RCSR symbol in the box under Find compatible topologies (for example tbo for HKUST-1) and press Build; it does not have to be in the ranked list. A symbol that does not exist is refused with the nearest real ones, and a net with no vertex for one of your units is refused with the reason. A net that is built but does not close is still opened, so you can see where it fails, and the line under the box says so. Quick relax beside it relaxes the atoms and the cell of the framework just built, and stops it while it runs.

3. Build it

Build this framework places the units on the selected net and opens the result in the workspace. You can then analyse, edit and export it.

The cell is fitted to the building units. Its dimensions are adjusted to bring paired connection points together. Using a longer linker therefore changes the cell size.

The framework is then deconstructed and its detected net is compared with the requested topology.

The report also checks for unused connection points, overlapping atoms and unlikely lengths of the bonds joining the units. Read these checks alongside the topology result.

A 2D net produces a monolayer with vacuum above and below it. The report gives two cell lengths and their angle. CIF export adds a third cell vector because CIF assumes periodicity in all three directions. The box is at least 30 Å tall, with at least 20 Å between the sheet and its periodic copy.

Build a chain without a topology

Draw or upload a unit with exactly two explicit attachment markers (X, *, R-group or sketcher attachment points), then choose Build 1D polymer without topology. Marked SMILES such as *CC* also work. Multiple units join in list order; the last joins the first across the cell boundary. Markers are removed and their anchor atoms form new bonds. Single and double marker bonds are preserved; the two sides of each junction must agree.

The chain repeats along the first lattice vector, with vacuum in the other directions. Internal unit geometry is retained while the units are aligned head to tail. Junction angles and torsions are starting guesses: use Quick relax (1D) beside the polymer builder, then inspect the chain before analysis. This uses the engine selected in Relaxation, optimises all atoms and the periodic chain repeat, and keeps the transverse vacuum vectors fixed. The button becomes Stop during optimisation; Undo restores the starting chain. It is also available for an open structure with one periodic axis. CIF represents the vacuum as part of a fully periodic cell.

For a drawn unit, edit reopens its drawing and saving replaces that entry. If the sketcher is unavailable, the unit opens in the workspace for 3D editing. Use the open structure as a unit saves it back to its original entry, preserving its bonds and coordinates.

4. Quick Relax it

Optimise is beside the build button. It becomes available when the generated framework is open in the workspace.

The cell relaxes with the atoms. Optimisation uses the engine selected in the Relaxation card. Before periodic UFF or an optional potential starts, crowded hydrogen groups are reoriented where their bonding allows it, and severe hydrogen overlaps receive a small displacement to help the optimiser separate them. The final check prevents unresolved nonbonded contacts below 1.2 Å from being reported as converged. If severe contacts remain at the start of a cell optimisation, the atoms are relaxed at fixed cell before the lattice can move. Both stages share the step limit. Cell relaxation checks cell forces as well as atomic forces. For a generated sheet, the perpendicular vacuum vector stays fixed while the periodic directions relax. All atoms must be free for cell optimisation.

After optimisation, the workspace contains the relaxed structure. The build report still describes the original generated geometry and is labelled accordingly.

Layer and polymer stacking

Open a periodic monolayer or bilayer, or generate a 2D COF in the Framework panel. Choose 2D stacking in the side rail. The controls use the structure currently open, including any edits or relaxation. Isolated monomers must first be assembled into a periodic sheet.

1. Choose AA, AB or Slip.
2. Leave Optimise interlayer distance on to calculate the separation, or turn it off and enter a spacing in angstrom.
3. Choose Create stack. The result opens in the viewer as a periodic two-layer cell.
4. Use Download CIF to save it. Undo returns to the input; redo restores the stack.

Registry and sequence

A monolayer is copied. For a bilayer, the existing translation is removed before applying the requested registry; the sheets must have matching compositions and parallel planes. Intralayer coordinates and bonds are retained. Remove unbound guests and attachment markers before stacking.

Spacing and dispersion

The spacing is the distance between the mean planes of adjacent sheets, rather than the closest atom-to-atom distance. Optimisation keeps the sheets rigid and searches the interval in Settings. Every constructed cell is checked for overlapping contacts, including periodic images; an invalid separation is refused.

Interlayer energy is calculated with UFF/UFF4MOF van der Waals parameters. Dispersion correction restores the long-range attraction omitted by the UFF cutoff, using the −C6/r⁶ term summed over periodic copies of the layers. The short-range interaction is retained and the attraction is counted once. This correction uses UFF parameters; D3 and D4 are not used.

The calculation repeats at larger cutoffs to check whether spacing and energy have settled. If they have not, open Check spacing for details. The API report includes energies, cutoff checks and warnings. With optimisation off, the report labels the spacing As supplied.

The model keeps each sheet rigid while choosing its separation from neighbouring sheets. It does not relax the atoms within a sheet or model stacking disorder. Use Match pXRD to compare possible stackings with a measured pattern.

Optimise interlayer distance

Optimise interlayer distance beside the polymer builder constructs a stack using the current registry and sequence, with separation optimised against interlayer energy. Internal atomic coordinates stay rigid. If a polymer has no supplied or previously recorded chain spacing, a starting chain spacing is estimated from molecular dimensions and held fixed; the result identifies this estimate. Use Fit distances to pXRD to search the distances against a measurement instead. That shortcut opens the upload controls if no measurement is present.

Stack a 1D polymer

With a periodic chain open, enter Chain spacing to set the transverse separation of parallel chains in a row, then create an AA, AB or slip stack. This creates a bulk cell without adding bonds between chains. No named topology is needed. The chain spacing must be large enough to avoid overlaps.

Fit stacking to a powder pattern

Choose Discover distances from pXRD to select search ranges automatically from molecular dimensions. The search varies interlayer distance and registry together. For polymers, leave chain spacing blank to search that distance too, or enter a value to hold it fixed. Up to 200 initial candidates are compared, then the leading fits are refined against the measured pattern. Effective ranges and fitted chain spacing appear in the fit details. A result near a search boundary is flagged so you can extend the range before interpretation. The manual Find matching stacks button uses the supplied interlayer range and a fixed chain spacing.

1. Keep your layer open and choose Match pXRD in the stacking card.
2. Upload a measured pattern and check its wavelength. A measurement already loaded in Analyse is used automatically. With several loaded, Fit all patterns fits them together.
3. Fixed spacing under Fit settings holds the interlayer distance where you put it and fits the registry alone - for a spacing already known from a 00l reflection, or held deliberately while the registry is examined. The minimum and maximum are what the spacing would be searched between, so they dim while it is set. Discovering distances is the feature that fits the spacing, so it refuses a fixed one rather than quietly dropping it - clear the box to use it.
4. Set the spacing interval under Fit settings, then choose Find matching stacks. The search compares AA, AB and a lattice-periodic grid of slip offsets, across five spacings, then refines the three leading candidates in both offset and spacing.
5. The best candidate is selected and its powder curve compared automatically. Select another candidate and choose Compare pattern to inspect it.
6. Choose Use stack to apply the selected geometry. The viewer updates, and Download CIF saves it. The operation can be undone and redone.

Candidates are ranked by similarity, with lower Rwp used to break ties. Rwp measures the difference between the calculated and measured profiles. Energy is shown when available but does not affect this ranking. Use stack keeps the fitted spacing and checks for overlaps before applying the result.

Open the fit details to see offsets, spacing, matched peaks and warnings. Candidates within 0.01 similarity of the best are shown as competing fits because the pattern may not distinguish them. This threshold is not a confidence interval. Check the layer structure, wavelength and spacing range if agreement is poor. Preferred orientation and disorder can also affect the fit. A wider spacing range or finer grid may find a better candidate.

The plot displays the square root of intensity to make weaker peaks easier to see. The comparison uses a common angular grid and a peak width estimated from the measurement, with background subtraction and intensity scaling. Fitting changes the layer offset and spacing, plus interchain spacing when automatic polymer fitting is requested without a fixed value. Internal coordinates, the chain repeat, the 2D layer lattice and the selected alternating or progressive sequence stay fixed. This is a fit of a chosen packing model, not an exhaustive search of crystal structures or proof of a unique packing.

You can stop a search or comparison while it runs. The open structure changes only when you choose Use stack. Repeat the fit after changing the structure or measurement, or after the stored result expires at 30 minutes. A search allows up to 200 initial candidates and checks its five-minute time limit between calculations.

To fit through the API, upload a measurement to POST /sessions/{session_id}/pxrd/experimental, then call POST /sessions/{session_id}/stack/fit with {"automatic": true} to choose ranges automatically, or supply spacing bounds, grid and sequence for a manual search. Supplying chain_spacing fixes that distance; omit it in automatic mode to fit it for polymers. Poll the returned job. The fit result contains ranked candidates, settings, warnings and an id. Send {"fit_id": "…", "candidate": 0} to /sessions/{session_id}/stack/fit/preview to compare the first candidate, or to /sessions/{session_id}/stack/fit/apply to use it. Candidate numbering starts at zero.

API

Send a request to POST /sessions/{session_id}/stack. For example:

{
  "mode": "slip", "x": 0.25, "y": 0.5, "units": "fractional",
  "sequence": "alternating", "optimise": true,
  "minimum": 2.0, "maximum": 8.0, "correction": true,
  "background": true
}

Poll GET /jobs/{job_id} for the result, which includes the updated structure, history and construction report. Export the stack through the session download route. To cancel, send DELETE /jobs/{job_id}. Cancellation records no edit; if the job has already finished, its result is retained.

Comparing against a measurement

Load a measured pattern in Experimental comparison and choose Compare. The instrument - background, scale, zero point, peak widths, preferred orientation - is fitted before anything is scored, and no atom and no cell moves. This is the same model Match pXRD uses, so the two report the same numbers for the same structure against the same measurement.

Refine the cell to a measured pattern

When the calculated peaks sit beside the measured ones rather than under them, the cell is off. Refine cell to the pattern, under the comparison, brings the structure onto the cell the measurement asks for without changing its chemistry. The peak positions fix the cell, so it is refined against the measurement: first with broadened peaks, which lets it travel several per cent, including a breathing framework whose axes move in opposite directions, then sharply. The crystal system is detected and kept, or you can choose it under Settings. Changing only the cell would stretch every bond with it, so the atoms are then placed on the new cell by distance least squares: every bond length and bond angle is held as close as it can be to its value in your structure, torsions are free and atoms are kept from coming closer than they were. Angles at metals and bridging oxygens may hinge, as frameworks do; angles at carbon and other rigid atoms are held firmly. Atomic positions are optimised once with the fitted cell fixed. The final diffraction fit is recalculated using those atoms. Stage and evaluation progress are shown while the job runs.

It never makes the structure worse. Every structure is judged the same way: the zero shift and peak widths fitted first, then Rwp and net Rwp (the residual over the peaks alone, without the background). A new cell is used only if it lowers Rwp without raising net Rwp, if no lattice parameter ended on the edge of the range it may move in, and if the framework keeps its bond lengths and rigid angles. Otherwise the structure is left as it is, with the instrument fitted, and the remarks say why. A fit that keeps improving all the way to the edge of the range is a sign that the model lacks something - another stacking, guests, a second phase - rather than that the cell is wrong.

Layers. For a structure made of separate layers, Fit layer stacking (under Settings, on by default) also fits how the layers stack, with the same search as Stack fit, and the leading stackings are judged exactly as a cell is. Stack fit ranks its leaders the same way, so applying a stack fit and then refining starts from the Rwp the stack fit showed. If no ordered stacking explains the peaks better than a single layer, the layers in the sample are probably not in register (turbostratic), and the structure is left unstacked.

Le Bail. Under Settings, choose Method: Le Bail to fit the cell with each reflection's intensity taken from the pattern itself instead of calculated from your atoms. The cell then depends only on where the peaks are, so a model that is wrong in some other way (stacking, guests, a missing phase) cannot pull it. Each cell parameter is given a standard uncertainty in the usual notation, 17.263(15) meaning 17.263 ± 0.015 Å, measured with the intensities re-extracted and corrected for the correlation between neighbouring points (Berar and Lelann). If any parameter is not pinned by the pattern - more than 1% of a length or 1° of an angle - the result says the pattern does not determine the cell and nothing is applied: a few broad peaks, or a large cell full of overlapping reflections, can fit several cells equally well. A determined Le Bail cell is then checked with your atoms exactly as any cell is, and used only if it fits better and keeps the framework intact.

The result shows the cell before and after with each change, Rwp before and after, how far bonds and rigid angles moved, and the space group. Chemistry kept means every bond within 0.03 Å of its length, no angle at a rigid atom bent more than 5°, and no atoms closer than before. When the cell cannot be reached that way the result says so instead: the measurement is then usually of a different phase, of pores holding guests or solvent or at another temperature. Nothing changes until you press Apply, and Undo takes it back. The search is local: a good fit is not a guarantee of a unique or correct cell. On StructSub Cloud refining needs an account, and a free account has three refinements a month.

Under the numbers, remarks holds what the fit says about itself - a profile Rwp that is mostly background, a parameter that fitted as far as it was allowed to go, a pattern that does not determine everything that was refined. Read them before trusting a good-looking number.

The peak lists are folded below the numbers: the matched reflections with their Miller indices, and - the half worth reading - calculated reflections above 5% of the strongest with nothing measured under them. A strong reflection that is simply absent is hard to explain away, where an extra measured peak may only be an impurity. Comparing the parent alongside is what makes a single number mean something: it says whether the edit is what moved the pattern towards the measurement.

Measured-pattern files

The experimental comparison in Analyse accepts XY, XYE, DAT, CSV, TSV, TXT, ASC, PRN, CHI, RAS, UXD, XRDML/XML, XLSX, JSON and powder CIF. The reader recognises common headers, separators and encodings; structured formats must contain a measured powder trace. Each file holds one scan, and every upload adds a pattern you can switch between. Check the wavelength and axis interpretation before comparing patterns.

Accounts, allowances and paying

Compare Standard, Pro and Lab on the pricing and subscription page. The allowances below are supplied by this server.

What you can do without signing in

Open a structure, select atoms, edit it, optimise it and analyse it within a small trial allowance. A visitor cannot download or build a framework; both ask for a free account instead. Keep the workspace open while you sign in.

Where the account controls are

1. Sign in or create an account by clicking the account icon at the top right of the workspace.
2. When signed in, the control is labelled Account. Open it to see your plan and remaining allowance.
3. The account panel also contains Account settings, upgrade options and billing controls when available.
4. Sign out is in that panel, at the bottom.

When the allowance runs out

If you are not signed in, the next trial-limited action opens Sign up to continue. Signed-in users see upgrade options when an allowance runs out.

A modification is anything that changes a structure or runs a real calculation: substituting, functionalising, replacing, adding or deleting atoms, removing guests, adding hydrogens, preparing a biomolecule, building or fitting a stack, relaxing and an analysis that includes topology or porosity. Each costs one. Framework builds are counted separately. Opening or building a file, selecting, undo and redo, bond corrections, matching topologies, deconstructing, the quick analyses, pattern comparison and project files are free, though rate-limited.

Paying, and stopping

Payment is handled entirely by Stripe: the workspace sends you there and never sees your card. Once you are subscribed, Manage billing & invoices in the account panel opens Stripe's own portal, where you can change your card, download invoices and cancel. A cancelled plan runs to the end of the period you have paid for, and the panel says which date that is.

A plan belongs to a workspace, not to a person, so everybody working in it shares the allowance. Only an owner or an admin can change what a workspace pays; a member sees the plan but is told who to ask.

Your structures and how long they are kept

The current workspace uses temporary editing sessions, not a saved-project library. Export work you want to keep. See Data retention for details.

Do I need an API key?

An API lets a script ask StructSub to do the same work you do in the interface. An API key is a credential some services use to identify that script. StructSub currently uses the access methods below.

What does “Bearer token” mean?

A token proves that a request belongs to a signed-in account. If your hosted integration already obtains a valid sign-in token, send it like this:

Authorization: Bearer YOUR_SIGN_IN_TOKEN

Replace the placeholder with a token issued through your deployment's sign-in flow. Tokens expire; integrations must refresh them through that flow. This guide does not generate or retrieve a token. Use the API reference to inspect each request and response.

Keep real tokens out of shared scripts and repositories. The downloadable example reads an optional token from STRUCTSUB_TOKEN and a server address from STRUCTSUB_URL. The local default server should stay bound to localhost; it does not provide authentication for a public deployment.

API reference lists endpoints and request fields. Its Try it out controls send real requests to this server; editing endpoints change the session you specify.

Connect Claude, ChatGPT or another AI assistant

StructSub's tools can be used from an AI assistant that supports the Model Context Protocol (MCP). The assistant can build and edit structures, run analyses and start calculations in your account, and it asks you to approve the long ones. It needs a Pro or Lab plan; calls count against the same allowance as the workspace.

Claude Code

claude mcp add --transport http structsub https://mcp.structsub.com/mcp

Then type /mcp in Claude Code, choose structsub and sign in.

Cursor, VS Code and other clients

Any client that connects to a remote MCP server over HTTP with OAuth sign-in works. Cursor reads ~/.cursor/mcp.json; VS Code reads .vscode/mcp.json in a project:

// Cursor: ~/.cursor/mcp.json
{ "mcpServers": { "structsub": { "url": "https://mcp.structsub.com/mcp" } } }

// VS Code: .vscode/mcp.json
{ "servers": { "structsub": { "type": "http", "url": "https://mcp.structsub.com/mcp" } } }

These apps rename their menus from version to version. If a label above is not there, look for custom connector, MCP server or integrations.

If it does not connect

• "MCP requires an active Pro personal or Lab group subscription": the account you signed in with has neither. Check the plan on the pricing page, or sign in with the account that has it.
• The sign-in page keeps coming back: remove the connector, add it again and sign in once more. Your browser must allow the sign-in window to open.
• A calculation waits: long calculations need your approval before they run. The assistant tells you, and you approve in StructSub.

A complete Python example

This example creates its own tiny periodic hydrogen structure, adds a bond across the a boundary, runs UFF optimisation and downloads the result. It needs no input file and uses the local server by default.

1. Use an existing StructSub server. The default address in this example is for a developer source checkout, not an installable public package.
2. In another terminal, install the HTTP client with python -m pip install httpx.
3. Download the script below and run python api_quickstart.py in an output folder.

The script writes relaxed.cif and relaxed-api.json in the current folder, replacing those filenames if they exist. The JSON retains exact API bond information for inspection. Check the printed convergence report.

"""Upload, add a periodic bond, optimise and download using the StructSub API.

Use an existing StructSub server. Install the HTTP client with `python -m pip install httpx`.
Run this script in a folder where you want to save the two output files.
Local use needs no API key. STRUCTSUB_TOKEN is an optional hosted sign-in token,
not a personal API key; hosted sign-in tokens expire.
"""

import json
import os
import time
from pathlib import Path

import httpx

BASE_URL = os.environ.get("STRUCTSUB_URL", "http://127.0.0.1:8000").rstrip("/")
TOKEN = os.environ.get("STRUCTSUB_TOKEN")

# Two H atoms whose closest connection crosses the a boundary.
# The 1.4 Å separation is deliberately stretched, so we add the bond ourselves.
SAMPLE = '''2
Lattice="12 0 0 0 12 0 0 0 12" Properties=species:S:1:pos:R:3 pbc="T T T"
H 0.2 0 0
H 10.8 0 0
'''


def finish(client, response, timeout=300):
    """Return an inline result, or wait for a queued job with a finite timeout."""
    response.raise_for_status()
    result = response.json()
    if not result.get("queued"):
        return result
    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        status = client.get(f"/jobs/{result['job']}")
        status.raise_for_status()
        job = status.json()
        if job["state"] == "done":
            return job["result"]
        if job["state"] in {"failed", "cancelled"}:
            raise RuntimeError(job.get("error") or f"Job {job['state']}")
        time.sleep(0.5)
    raise TimeoutError("Stopped waiting; the server job may still be running.")


def main():
    headers = {"Authorization": f"Bearer {TOKEN}"} if TOKEN else {}
    # One client retains trial cookies if using a hosted deployment.
    with httpx.Client(base_url=BASE_URL, headers=headers, timeout=120) as client:
        uploaded = finish(client, client.post(
            "/sessions", files={"file": ("stretched-hydrogen.extxyz", SAMPLE.encode())},
        ))
        session = uploaded["session"]
        print(f"Session: {session}")
        if uploaded.get("warnings"):
            print("Connectivity warnings:", uploaded["warnings"])

        finish(client, client.post(f"/sessions/{session}/bonds", json={
            "i": 0, "j": 1, "offset": [-1, 0, 0],
        }))
        relaxed = finish(client, client.post(f"/sessions/{session}/relax", json={
            "engine": "uff-periodic", "scope": "all", "max_steps": 200,
            "optimise_cell": False, "background": True,
        }))
        print(relaxed["report"]["summary"])
        print("Converged:", relaxed["report"]["converged"])

        exported = client.get(f"/sessions/{session}/download", params={"format": "cif"})
        exported.raise_for_status()
        Path("relaxed.cif").write_bytes(exported.content)
        # Keep the explicit bond indices and offsets too. This is an API
        # snapshot for inspection; it is not an importable session file.
        Path("relaxed-api.json").write_text(json.dumps(relaxed, indent=2))
        print("Saved relaxed.cif and relaxed-api.json")


if __name__ == "__main__":
    main()

Prefer curl? Check the connection first.

curl https://structsub.com/health

A working server returns JSON with "status": "ok". For a different port or hosted deployment, use its actual address.

Upload once. Work within a session.

A session holds a structure and its edit history. Upload a file, copy the returned session value and use it in later request paths. In the examples below, replace SESSION_ID with that value.

1. Upload a structure

curl -F "file=@framework.cif" https://structsub.com/sessions

The upload is multipart form data with the field name file. The response includes session, structure and warnings. Most later requests send JSON instead.

2. Find sites without editing

curl -X POST https://structsub.com/sessions/SESSION_ID/select \
  -H 'Content-Type: application/json' \
  -d '{"selector":"atoms","indices":[0,1]}'

This returns selection information. It does not change the structure or automatically set the atom indices for a later edit; include the indices in that edit's request.

3. Add a specific periodic bond

curl -X POST https://structsub.com/sessions/SESSION_ID/bonds \
  -H 'Content-Type: application/json' \
  -d '{"i":0,"j":1,"offset":[-1,0,0]}'

This connects atom 0 to atom 1 one cell back along a. Use indices from your structure. The connection must not already exist, and a must be periodic. Omitting offset means [0,0,0].

4. Optimise with the current bonds

curl -X POST https://structsub.com/sessions/SESSION_ID/relax \
  -H 'Content-Type: application/json' \
  -d '{"engine":"uff-periodic","scope":"all","optimise_cell":false,"max_steps":500,"background":true}'

With background: true, poll the returned job before downloading the result. For a standalone optimisation use scope: "all"; fragment and shell scopes require a seed supplied by an editing operation.

5. Download or undo

curl -o edited.cif https://structsub.com/sessions/SESSION_ID/download?format=cif
curl -X POST https://structsub.com/sessions/SESSION_ID/undo

Undo steps back one operation; /redo steps forward again. Deleting atoms changes subsequent indices, so use the structure returned by the latest edit.

Mechanical properties

Under Analyse → Mechanical properties, select Calculate. The calculation relaxes a copy of the atomic positions and lattice, then measures the response to small positive and negative strains. The original structure stays in the viewer until you choose Load optimised.

Model decides how good the numbers are. Accurate is MACE-MP-0b3 with D3 dispersion, a machine-learned potential: it takes minutes, and for MOFs it lands close to DFT. For IRMOF-1 it gives C₁₁ 24.9, C₁₂ 9.5, C₄₄ 0.95 and a bulk modulus of 14.7 GPa, and its relaxed cell is within 1% of experiment. Fast is the UFF4MOF force field: seconds, but stiffer (the same crystal gives 47.4, 6.6, 2.1 and 20.2 GPa), and it cannot describe a framework that breathes, where it can move the cell by several per cent and report an instability that is not there. The force field is the default: choose MACE-D3 when the numbers matter (it needs a paid plan on StructSub Cloud). MACE is weakest on shear moduli, as its authors report. The report names the model used.

Strain is dimensionless: 0.002 is 0.2%; MACE uses at least 0.5%, because its forces are noisier than a force field's. The calculation also checks half this strain. Step limit applies to each optimisation; increase it if a calculation has not converged. The (i) controls explain settings and show checks and warnings.

Report downloads a formatted HTML document containing elastic tensors, Voigt/Reuss/Hill moduli, convergence checks and the reference cell. Open it in a browser and use Print to save a PDF. The report also contains a link to the numerical JSON data and reference coordinates.

Export data downloads the same calculation as tables rather than as a document: CSV, TSV, Markdown, an Excel workbook or the full JSON. A calculation is several tables - two stiffness tensors, a compliance, the moduli, the checks and the settings - so a single CSV carries them one after another behind # comment lines, while a workbook gives each one its own sheet. Exported numbers are not rounded. Use the CLI's --table if you need one bare grid that a data-frame reader will accept.

Load optimised loads the equilibrium reference into the viewer, retaining its bonds. It becomes the current structure for further analysis and CIF export. Undo restores the previous structure. Loading is unavailable if the reference has not reached equilibrium or if the structure has changed since calculation.

Results describe the zero-temperature UFF4MOF model. Hill averages approximate an isotropic polycrystal; they are not directional single-crystal properties. Provisional chemistry remains provisional even when the calculation converges. The report withholds derived moduli when numerical or stability checks fail.

Strain analysis

Under Analyse → Strain analysis, select Calculate. It answers two questions about a relaxed copy of the structure, bond by bond: where it is soft, and where a deformation stores its strain. The result is drawn on the structure as a heat map, blue where little happens and red where most does, and the structure on screen is not changed.

Soft points needs no deformation. It gives every bond, angle and torsion a compliance constant: how far it moves under a unit force with every other coordinate, and for a crystal the cell too, free to follow (Brandhorst and Grunenberg, Chem. Soc. Rev. 2008). Unlike a force constant it does not depend on which coordinates are chosen. The map colours each one by its rank among its own kind, from the stiffest (0) to the softest (1), and the table lists the softest with their relaxed force constants in mdyn/Å or aJ/rad².

Strain (JEDI) deforms the copy and shares the strain energy among every bond, angle and torsion: the JEDI analysis (Stauch and Dreuw, J. Chem. Phys. 2014; Wang, Benter, Dononelli and Neudecker, 2024). A crystal is deformed through its cell with the atoms relaxed at each step. Automatic takes the softest relaxed elastic mode, computed from the same Hessian; in a breathing framework that is the breathing motion, and for MIL-53 it opens one axis while closing the other. Uniform, Along a, b or c and Shear (the softest change of shape at constant volume) are the alternatives, compressed by default and stretched under Settings. A molecule is pulled along two atoms, the two you pick or the two heavy atoms farthest apart, with their distance held and everything else relaxed.

Amount is 1, 5, 10 or 15%, or any value up to 30% under Custom. 1% stays where the harmonic picture holds. A larger deformation is taken in 1% steps, and at each one the work done on every coordinate is added up: this path work adds up to the model's own strain energy at any amplitude, and it is what the map shows by default. The harmonic JEDI share, which is exact only for small deformations, is shown beside it; Harmonic check says how far apart the two totals are, and a torsion that turns past 60 degrees is reported, since its harmonic energy then means nothing. A bond's colour is its own stretch, half of each angle it is an arm of and a third of each torsion it belongs to, as in the JEDI pictures.

Model is the force field, UFF4MOF, by default: a few seconds for a framework of a few hundred atoms. MACE-D3 (MACE-MP-0, a machine-learned foundation potential, with D3 dispersion) takes minutes to an hour and needs a paid plan. GFN2-xTB, a tight-binding quantum method, also needs a paid plan, runs in the background and is limited to 200 atoms. A crystal is reduced to its primitive cell first and the result mapped back onto every bond. The analysis is limited to 1200 atoms with the force field and 300 with MACE, after that reduction.

Read the checks behind the (i). The analysis is expanded about the relaxed reference, so a reference that is not a minimum (it reports directions of negative curvature, or an elastic tensor that is not positive definite) gives shares that describe a structure falling into another one, not one being strained. UFF4MOF on MIL-53 and MACE-D3 on large-pore MIL-53 are both examples. Angles of 175 degrees or more, and the torsions through them, are left out, because a linear angle has no well-defined derivative there; the other angles at that centre still carry its strain. The analysis is at zero temperature.

Load deformed puts the deformed copy in the viewer as an ordinary edit, which Undo takes back. Export data writes a summary, every coordinate (value, change, path work, harmonic share, compliance, relaxed force constant and softness rank) and every bond, as CSV, TSV, Markdown, an Excel workbook or JSON.

structsub strain-analysis MIL-53.cif --amplitude 5 --report strain.xlsx

curl -X POST https://structsub.com/sessions/SESSION_ID/strain \
  -H 'Content-Type: application/json' -d '{"method": "jedi", "amplitude": 0.05}'

Vibrations and IR

Under Analyse → Vibrations and IR, select Calculate. A copy of the structure is relaxed first, its atoms and for a crystal its cell, because frequencies describe a structure only at a minimum. Then every normal mode is found from the same second derivatives the strain analysis uses. The structure on screen is not changed until you choose Load relaxed, which Undo takes back.

The result is an infrared spectrum, drawn as infrared spectra are read, high wavenumber on the left. Click a band, or a row of Strongest bands, and the atoms move along that mode in the view; Stop puts the structure back. A crystal gives its modes at the centre of the Brillouin zone (the Gamma point), the ones light can excite. Translations, and for a molecule rotations, are removed and not counted.

Frequencies come from the energy model. UFF4MOF, the default, takes seconds for a molecule and a minute or a few for a framework of a few hundred atoms; its frequencies show the pattern but can be off by a few hundred cm⁻¹ (it puts CO₂'s bend at 984 cm⁻¹ against 667 measured). MACE-D3 is closer to measurement and needs a paid plan. GFN2-xTB, a tight-binding quantum method, needs a paid plan too; for a molecule it gives real intensities, from how its own dipole moment changes along each mode (CO₂'s antisymmetric stretch at 1047 km/mol against 69 for the bend), and for a crystal its own atomic charges. The limit is 600 atoms with the force field, 150 with MACE and 200 with GFN2-xTB.

Intensities are an estimate. An infrared intensity measures how much a mode changes the dipole moment, and neither model gives a dipole. Each atom is given a fixed partial charge (supplied with the structure, the trained charge model or charge equilibration) and the intensity follows from how the charges move. Symmetry is right (CO₂'s symmetric stretch is silent; methane absorbs in its two triply degenerate modes only), and the strong bands of polar groups appear. Bands that come from charge flowing along a bond, such as C=O, can come out too weak.

A badge reads Minimum when every frequency is real. Imaginary modes mean the relaxed structure is a saddle point along them, not a minimum; they are not drawn. UFF4MOF on MIL-53 is an example. Export data writes every mode with its frequency and intensity as CSV, TSV, Markdown, an Excel workbook or JSON.

curl -X POST https://structsub.com/sessions/SESSION_ID/vibrations \
  -H 'Content-Type: application/json' -d '{"model": "uff4mof"}'

Ion migration

Under Loading, choose Ions; Ion migration sits below ion insertion. Choose the Mobile ion and select Find migration paths. The menu lists the ions in your structure first, then common battery ions, then every ion with published parameters: Li⁺, Na⁺, K⁺, Mg²⁺, Ca²⁺, Zn²⁺, Al³⁺, Ag⁺, Cu⁺ and many more, and anions such as F⁻, O²⁻ and Cl⁻. An ion the structure does not contain is treated as one inserted into it.

Two models describe the ion's energy, and Model is Automatic by default. Bond valence is for inorganic solids such as oxides, sulfides, halides and phosphates: the energy comes from how strongly the ion bonds to its neighbours, with the softBV parameters. Force field is for frameworks with organic linkers, MOFs and COFs, where bond valence does not apply: UFF and the framework's partial charges, as the adsorption tools use. Automatic picks the force field when any carbon is bonded to carbon or hydrogen. In the force field, ions of the same element already in the framework are taken out first, since they move with the test ion rather than block it.

The ion's energy is mapped through the cell on a 0.1 Å grid (0.2 Å for the force field), with every other ion held where it is. The table gives the barrier to conduction in one, two and three dimensions: the lowest energy at which the low-energy regions join into a path that crosses the crystal along a line, over a plane or in every direction, and which directions open. A barrier of none means no such path exists below 5 eV. The heading names the conductor by the dimensions that open below 1 eV.

Channels in the view draws the surface enclosing where the ion's energy is below Energy shown. It starts just above the lowest barrier, so the easiest channel appears joined up; raise it to watch the next dimension connect. The surface follows the Cells repeats and is removed when the structure changes.

This is a screening method. It ranks conductors and finds their paths and dimensionality well; absolute barriers are usually within a few tenths of an electronvolt of experiment. LiFePO₄, for example, gives 0.44 eV along its b channels and more than 3 eV between them. The bond-valence parameters are the softBV set of Chen and Adams (IUCrJ 2017), published under CC-BY 4.0. Oxidation states are assigned automatically; through the API you can give them with oxidation.

curl -X POST https://structsub.com/sessions/SESSION_ID/ions/migration \
  -H 'Content-Type: application/json' -d '{"element": "Na", "charge": 1}'

Barrier and conductivity

After the quick map come two steps that let the atoms move: Calculate barrier and Calculate conductivity. Accuracy chooses the model for both. Fast (force field), the default, is a force field built from the same softBV bond-valence parameters as the map (Adams and Rao, 2011). The mobile ions move freely and the other atoms are held near their crystal positions by springs, which let them relax about a tenth of an ångström around a hopping ion. The springs are needed because softBV was fitted to how a mobile ion sees its host, not to how the host holds itself together: left free, the PS₄ tetrahedra of Li₇P₃S₁₁ collapse. It covers oxides, sulfides, halides, nitrides and phosphates, but not carbon: frameworks with organic linkers, graphene and graphite use Balanced or Accurate, and the menu says so. Accurate (MACE) is MACE-MP-0 (MIT weights) with D3 dispersion, a machine-learned potential in which every atom moves. Balanced (MACE, path scan) uses MACE for the barrier without a full band. The ion is placed at 13 points along the map's path, with the atoms within 6 Å of the hop relaxed at both ends. Then only the highest points are relaxed, with the ion held at its fraction of the way from one site to the other, until no unrelaxed point lies above the highest relaxed one. Against the band it gives 0.30 against 0.30 eV for LiFePO₄, 0.14 against 0.16 eV for Li₇P₃S₁₁, 0.015 against 0.006 eV for Li₃N, and 0.105 against 0.099 eV for Li between two graphene sheets, where it takes 4 minutes to the band's 9. It relies on the map's path to place the ion, so for a number to report, use Accurate. The conductivity has no scan, so under Balanced it runs as Accurate. Frameworks and carbon hosts start on Balanced.

Calculate barrier takes the hardest hop on the easiest path, relaxes both ends in a supercell at least 9 Å across, and finds its highest point with a climbing-image nudged elastic band, started along the map's own curved path. If both ends hold the ion, one is taken out and the other hops into the vacancy; if the structure has none, one is inserted. The energy profile shows the climb, and the slider moves the ion through the hop in the view. For a cell of a hundred atoms it takes a few seconds with the force field and two to three minutes with MACE on a four-core server.

Calculate conductivity runs molecular dynamics at several temperatures (600, 800 and 1000 K by default; 50 ps each with the force field, 5 ps with MACE) with the Bussi thermostat, and takes each temperature's diffusivity from the mean squared displacement. An Arrhenius fit gives the activation energy and extends the diffusivity to 300 K; the Nernst-Einstein relation turns that into a conductivity. The structure must already hold the ion, so place some with Ion insertion first; one vacancy is made by default. A temperature at which the ions made fewer than 20 hops between them is marked and left out of the fit: run it longer or hotter. It takes a minute or two with the force field and tens of minutes with MACE.

Before calculating the conductivity, make sure the structure is one that exists. The ions should be no closer together than in the real compound, and the structure relaxed with its cell free. The common mistake is inserting one ion into a small cell: one Li in graphite's four-atom cell puts a Li every 2.46 Å, about three times as dense as LiC₆, and in graphite's AB stacking at its unexpanded spacing. Heated, such a structure rearranges, and that movement is not diffusion. Use Final formula in Ion insertion on a cell large enough to hold the real composition (LiC₆ needs at least a 3 × 3 graphite cell, which Build from a specification makes as a Supercell), then relax it before calculating.

The result checks itself for two signs that a run did not measure diffusion, and says so beside the numbers. The mean squared displacement of diffusing ions grows in a straight line with time; if it curves upward (grows faster than t^1.3), the ions or the host moved together, and that temperature is left out of the fit. And heat always speeds diffusion, so a diffusivity that falls as the temperature rises means the structure changed during the run. A fit that still gives an activation energy of zero or less shows no room-temperature value.

How the two compare. LiFePO₄'s hop along b: 0.35 eV with the force field, 0.30 eV with MACE, 0.27 to 0.30 eV by DFT. Li₇P₃S₁₁: a barrier of 0.24 eV with the force field and 0.16 eV with MACE; from the force field's dynamics, an activation energy of 0.23 eV and 1 × 10⁻² S/cm at 300 K, against measured values of 0.18 eV and 3 × 10⁻³ to 1.7 × 10⁻² S/cm. The force field is weakest where a hop is almost free: Li₃N's in-plane vacancy hop is 0.15 eV with it, 0.006 eV with MACE. Use Fast to compare materials and for a first number, and Accurate for the number you report. Machine-learned foundation potentials such as MACE-MP-0 are more often too soft than too stiff, so expect either model within a few tenths of an electronvolt, and a conductivity that can be off by an order of magnitude; for a number to publish, check the hop with DFT. On StructSub Cloud both steps need a paid subscription, whichever model is chosen.

Each result leads with its number: the barrier, or the conductivity at 300 K with the activation energy. The rest (the quick estimate, the reverse barrier, the hop length, each temperature's diffusivity and how it was all calculated) is behind the (i). Play moves the ion along its hop, the ring on the energy plot following it, or runs the dynamics with the mean squared displacement growing beside the ions: the curve whose slope is the diffusivity. The slider steps through either by hand. Save writes the numbers (CSV or JSON), a figure (SVG or PNG) or a report (a LaTeX folder with the figure and its references, or text). Movie opens the recorder with the run chosen and its plot growing beside it; a hop is slowed to last a few seconds. A picture from Export as can carry the plot on show beside the structure too. Conductivity needs the ions in the structure: place them with Ion insertion first.

Some requests return a job

A short operation returns its result immediately. A background operation first returns a response like this:

{"queued": true, "job": "JOB_ID", "poll": "/jobs/JOB_ID", "state": "pending"}

Check GET /jobs/JOB_ID periodically. The Python example above includes polling with a timeout.

DELETE /jobs/JOB_ID stops a job. Work that has not started is dropped; a running calculation stops at its next checkpoint, so poll until the state is cancelled. A client timeout does not stop work on the server.

Reports

Export as > Report writes up the whole session as Word, a LaTeX folder (report.tex, references.bib and the figures, ready for a manuscript) or text. It says where the structure came from, describes every preparation step as the methods section of a paper (each model named and cited), includes the results the page holds for the structure, discusses them, states the limits of the models and ends with a reproducibility table of every step and its exact settings. Nothing is recalculated: the report is the session's own record, written out.

Long calculations run in the background

Adsorption (isotherms, selectivity, GCMC, flexible frameworks), diffusion, ion migration, mechanical properties, optimisation with a machine-learned model such as MACE, and cell refinement against a measured pattern can take an hour, so they do not hold the workspace. They run on a copy of the structure taken when you press the button, and you can keep editing, undo or open another structure meanwhile. Each one is listed under Jobs in the drawer at the bottom, with Stop. When it finishes the activity log says so, the tab title shows a count if you are elsewhere, and the browser notifies you if you allowed it.

A result belongs to the structure as it was when the job started. If that is still the structure on screen, the result appears where you asked for it. An optimisation is applied as an ordinary edit, which Undo takes back. If you have edited the structure since, press Show under Jobs: the result opens beside its own structure as a new workspace (for an optimisation, the optimised structure), so it is never drawn over a structure it was not computed for. Save a project file first if you want to keep the current one.

Through the API, the response to such a request also carries "background": true and a label. POST /jobs/JOB_ID/open opens the structure the job ran on as a new session. On StructSub Cloud, finished results are kept for a few days and then deleted (the number is under Data retention), and stopping a job in its first minute of running costs nothing; after that it counts against your allowance like a finished one.

Common questions