> ## Documentation Index > Fetch the complete documentation index at: https://docs.revilico.bio/llms.txt > Use this file to discover all available pages before exploring further. # RevSpin > Spin-state energetics: compare the energies of different spin multiplicities of one molecule and find its ground state ## Why Use This Engine? RevSpin calculates the energy of one molecule in several spin states and ranks them. You list the spin multiplicities you want to compare, such as singlet, triplet and quintet, and RevSpin returns the total energy of each state, its energy relative to the lowest state, and a spin-contamination check. The lowest-energy state is reported as the ground state. Use RevSpin when the spin state of a molecule is not obvious or matters to your result. Typical uses: * **Find the ground spin state.** Transition-metal complexes, carbenes, nitrenes and some radicals can have a high-spin or a low-spin ground state, and the answer is not always clear from the structure. * **Measure spin-state gaps.** The relative energy tells you how far each excited spin state lies above the ground state, in kcal/mol. * **Choose the multiplicity for other calculations.** Run RevSpin first, then use the ground-state multiplicity as the input for other quantum chemistry engines. * **Check open-shell results.** The spin-contamination values flag states whose unrestricted wavefunction is not a clean spin state. Each run takes one molecule, as a SMILES string or an XYZ block. RevSpin Workflow ## Background An atom or molecule's **spin multiplicity** counts how many ways its total electron spin $S$ can be oriented: $$ M = 2S + 1 $$ Each unpaired electron contributes $S = \tfrac{1}{2}$, so a molecule with no unpaired electrons is a singlet ($M = 1$), one unpaired electron gives a doublet ($M = 2$), two give a triplet ($M = 3$), and so on. A molecule with an even number of electrons can only have odd multiplicities (1, 3, 5, ...). A molecule with an odd number of electrons can only have even multiplicities (2, 4, 6, ...). Different spin states of the same molecule have different electronic energies, and often different preferred geometries. The **spin-state energy gap** between a state and the ground state is $$ \Delta E = E_{M} - E_{\text{ground}} $$ where the ground state is the multiplicity with the lowest total energy. Small gaps, of a few kcal/mol, are common in transition-metal chemistry and are sensitive to the method used. RevSpin runs in **Rapid** mode, written `r²SCAN-D4/vDZP // GFN2-xTB`. The part after `//` is the method for the geometry and the part before it is the method for the energy: * **Geometry:** GFN2-xTB, a fast semi-empirical tight-binding method. * **Energy:** a single-point DFT calculation with the r²SCAN meta-GGA functional and the vDZP basis set, plus the D4 dispersion correction. The total energy of each state is the SCF energy plus the dispersion correction: $$ E_{\text{total}} = E_{\text{SCF}} + E_{\text{D4}} $$ **Spin contamination.** Open-shell states are usually calculated with an unrestricted wavefunction, which can mix in contributions from higher spin states. For a pure spin state, the expectation value of the total spin operator is $$ \langle S^2 \rangle_{\text{exact}} = S(S + 1) $$ so a triplet should have $\langle S^2 \rangle = 2$ and a quintet $\langle S^2 \rangle = 6$. A calculated $\langle S^2 \rangle$ well above the exact value means the state is contaminated, and its energy is less reliable. ## Running the Engine Open **Quantum Chemistry** > **RevQuant** > **RevSpin**. The page has two tabs: **Spin States** to set up a run and **Analysis** to view results. Enter a **Pipeline Name**. It is required and defaults to "Spin-State Energies". Under **Molecule Format**, select **SMILES** or **XYZ (Cartesian)**. See [Preparing the molecule](#preparing-the-molecule). Paste a single SMILES string into **SMILES**, or a full XYZ block into **XYZ Block**. Enter the net **Charge** and the **Initial Multiplicity** for the reference geometry. In **Spin States (Multiplicities)**, list the multiplicities to compare, separated by commas, for example `1,3,5`. Enter a **Runtime Limit (Credits)** to cap what the run can spend. Leave it blank for no cap. See [Run time and credits](#run-time-and-credits). Click **Run Analysis**, then confirm. A notification links to the **Command Center**, where you can follow the run, and the page switches to the **Analysis** tab. ### Inputs | Setting | Default | Options and notes | | - | - | - | | Pipeline Name | Spin-State Energies | Required | | Molecule Format | SMILES | SMILES, XYZ (Cartesian) | | Mode | Rapid | Rapid (`r²SCAN-D4/vDZP // GFN2-xTB`) is the only mode | | SMILES or XYZ Block | Required | One molecule per run | | Charge | 0 | Net molecular charge, as an integer | | Initial Multiplicity | 1 | 2S+1 for the reference geometry. Must be 1 or more | | Spin States (Multiplicities) | `1,3,5` | Comma-separated positive integers. All must be odd or all even, with no duplicates | | Runtime Limit (Credits) | Blank (no limit) | Minimum 10 credits. The run stops when it reaches this limit | Pick multiplicities that match the molecule's electron count. For a neutral closed-shell organic molecule or an even-electron metal complex, use odd values such as `1,3,5`. For a radical or an odd-electron complex, use even values such as `2,4,6`. ### Preparing the molecule **SMILES.** Enter a single SMILES string, for example `O` for water or `[Fe+2]` for an iron(II) ion. SMILES have no 3D geometry, so the starting structure is built with RDKit 3D embedding and the MMFF force field. **XYZ.** Paste a standard XYZ block: the atom count on line 1, a comment on line 2, then one line per atom with the element symbol and its x, y and z coordinates: ```text theme={null} 3 water O 0.000 0.000 0.117 H 0.000 0.757 -0.469 H 0.000 -0.757 -0.469 ``` An XYZ block does not carry the charge, so always set **Charge** to match the structure. **Charge** applies to SMILES input too. Set it to the net charge of the molecule, for example `2` for `[Fe+2]`. ### Run time and credits Run time grows with the size of the molecule and the number of spin states you request. Transition-metal complexes and larger molecules can take several minutes or more. RevSpin bills 1 credit per minute of runtime while the run is in progress. You need enough credits to start a run: at least 10 credits, or your **Runtime Limit (Credits)** if you set one. With a runtime limit, the run stops when it reaches the limit and ends with the status `terminated_budget_exceeded`. With the field blank, there is no cap. ## Viewing Results Open the **Analysis** tab. The table lists your completed RevSpin runs. Click a run to open its results, and click **Back to pipelines** to return to the list. Runs that are still in progress, failed or were stopped do not appear in this list; follow them in the **Command Center**. ### Run statuses | Status | Meaning | | - | - | | `not_started` | Submitted and waiting for compute | | `started` | Running | | `processed` | Finished. Check each state's status in the **Per-State Energies** table | | `error` | The run failed | | `terminated_budget_exceeded` | Stopped because the run reached its **Runtime Limit (Credits)** | ### Summary The **Summary** card shows: | Field | Meaning | | - | - | | Mode | The calculation mode, such as Rapid | | Level of Theory | The methods used for the energies and geometries | | States Requested | How many spin states were calculated | | Ground State | The multiplicity with the lowest total energy | | Wall Time (s) | Total run time in seconds, when available | ### Per-state energies The **Per-State Energies** table has one row per requested multiplicity. The ground state row is highlighted and carries a **ground** badge. | Column | Meaning | Units | | - | - | - | | Multiplicity | The spin multiplicity, 2S+1 | | | Total Energy | SCF energy plus D4 dispersion | Hartree (Eh) | | SCF | Electronic (SCF) energy | Hartree (Eh) | | D4 | D4 dispersion correction | Hartree (Eh) | | Relative | Energy relative to the ground state | kcal/mol | | \ | Calculated expectation value of the total spin | | | Contamination | Spin contamination of the state, as reported by the engine | | | Status | **processed** or **failed** for that state | | A value the engine did not return is shown as a dash (—). Compare **\** with the exact value $S(S+1)$ for each state: 0 for a singlet, 0.75 for a doublet, 2 for a triplet, 3.75 for a quartet and 6 for a quintet. A large excess means the state is spin-contaminated, so treat its energy and the gaps that involve it with caution. A run can finish as `processed` even if some states failed. Check the **Status** column, and do not use the energies of a state marked **failed**. ### Downloads Click **Download JSON** in the results view to get **`spin_states_results_{pipelineId}.json`**. It is the full results document for the run, including the mode, level of theory, the per-state energies and spin data, the ranking of states by relative energy and the ground-state multiplicity. ## Limits * One molecule per run. * Rapid (`r²SCAN-D4/vDZP // GFN2-xTB`) is the only calculation mode. * All requested multiplicities must share the same parity (all odd or all even) and must not repeat. * Geometries come from GFN2-xTB, a semi-empirical method, not from DFT. * The **Analysis** tab lists completed runs only. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.