User guide

How to use Rotamer, screen by screen—for learners and teachers. Quoted Portuguese labels are the ones shown in the app, with their English meanings alongside them.

The editor opens without registration: visit the address and start drawing. An account is only needed to save progress and molecules, join a class, and give a structure a nickname.

1. The workbench

The drawing screen fills the page; everything else sits around its edges.

Where	What
Top bar	the brand, the formula and mass of the drawing, its status (`válida`—valid, `estrutura impossível`—impossible structure, `carregando o motor`—loading the engine), `Guardar` (Save), `Exemplos` (Examples), `Missões` (Missions), `Análise` (Analysis), and `Entrar` (Sign in) or your name
Vertical toolbar on the left	tools, elements, ready-made rings, cleanup, undo and redo, fit to view, new molecule, shortcuts
Bottom bar	five values that change with every stroke—mass, TPSA, rotatable bonds, rings, donors/acceptors—and the rule of five
Bottom-right corner	the 3D scene, which folds and vibrates
Side panel	closed by default: `Análise` (Analysis: everything RDKit calculated) and `Missões` (Missions: the story and tutor)

On mobile, everything stacks: drawing above, panel below. Nothing requires a mouse.

2. Drawing

Click an empty area to place an atom of the active element (carbon, initially). A single carbon is already methane: hydrogens are implicit.
Drag from an atom to create another atom already bonded to it. The angle snaps to 30°, and the chain comes out in a zigzag, just like on the board.
Click a bond to cycle its order: single, double, triple, single.
Active element: the C N O S toolbar buttons, or ··· for the entire periodic table. With an element selected, click an atom to replace it or an empty area to place a new one.
Ready-made rings: benzene, cyclohexane, cyclopentane, and pyridine, in one click.
Clean up the drawing: RDKit recalculates positions—equal bond lengths, correct angles, regular rings. Ctrl+Z restores the previous drawing. If there were wedges, a banner at the top explains what happened to them (§ 5).
Undo and redo: Ctrl+Z and Ctrl+Shift+Z (or Ctrl+Y), with no limit within the session.
New molecule: clears the screen; Ctrl+Z brings it back.

Tools (shortcut in parentheses):

Tool	What it does
Draw (`D`)	the normal mode, described above
Move (`M`)	drags an atom without creating anything; dragging an empty area pans the view
Select (`V`)	a rectangle selects several atoms; double-click selects the entire fragment; dragging from inside moves the block; `Delete` deletes everything at once; `Ctrl+A` selects all; `Esc` clears the selection
Stereochemistry (`W`)	click a bond to add a solid wedge; click again for a hashed wedge; again to remove it. The narrow end belongs at the stereogenic center
Erase (`E`)	click an atom or bond

Shortcuts work throughout the page, except while you type in a text field. ? opens the sheet listing them all. Elements: C N O S P F I H, plus L for chlorine and B for bromine. 0 fits the molecule to the view.

Right-click menu (on mobile, long press): on an atom, change its element with the miniature periodic table, set formal charge, delete; on a bond, choose its order directly and its stereochemistry (solid wedge, hashed wedge, reverse the narrow end); on empty space, clean up, fit to view, undo, clear; with a selection, change every element or bond order at once, deselect, delete.

On mobile: use two fingers to zoom in and out; double-tap selects the fragment; long press opens the menu.

3. Reading the screen

The top bar shows the formula and mass as soon as the structure is valid, plus its status:

válida (valid)—RDKit accepted it.
estrutura impossível (impossible structure)—and the bottom bar explains why, in Portuguese: “O átomo de C tem 5 ligações, mas suporta no máximo 4.” (The C atom has 5 bonds, but supports at most 4.) A dashed circle marks the problem atom. Ver o que fazer (See what to do) opens the panel with the explanation and correction.
carregando o motor (loading the engine)—RDKit is still starting up (once per visit; then it stays cached).

The bottom bar: mass (g/mol), TPSA (Å²), rotatable bonds, rings (including how many are aromatic), hydrogen-bond donors/acceptors, and whether the molecule falls within Lipinski’s rule of five. Everything is calculated by RDKit, with every stroke.

Where RDKit differs from another table, the screen shows RDKit’s value and identifies whose definition it uses. Caffeine has TPSA 61,82 (PubChem publishes 58,44—the difference is aromaticity perception); aspirin has 2 rotatable bonds under the strict definition (PubChem counts 3).

4. The Analysis panel

SMILES or name. Paste a SMILES (CC(=O)Oc1ccccc1C(=O)O) and choose Carregar (Load). Anything RDKit cannot read as a structure becomes a PubChem name search: caffeine, aspirin. If PubChem does not respond, the screen tells you—pasting SMILES still works.
Examples (Exemplos, in the top bar): ethanol, acetic acid, benzene, paracetamol, aspirin, caffeine.
Recognized functional groups, named in Portuguese: ester, carboxylic acid, amide…
Identity: heavy atoms, heteroatoms, rings, rotatable bonds, donors/acceptors, TPSA, logP, molar refractivity, sp³ fraction, stereocenters (and how many have unspecified configuration), exact mass, InChIKey, SMILES.
Normal modes: 3N − 6 modes (3N − 5 for a linear molecule), each with its wavenumber in cm⁻¹ and whether it is stretching or bending. Click a mode and the scene shows only that mode. Frequencies come from the MMFF94 force field, calculated on the spot—they are not measured spectra, and the screen explains that classical force fields tend to overestimate stretching by 5% to 10%. A mode with a negative number represents an imaginary frequency, and the screen explains what that means.
Rule of five: four bars—mass, logP, donors, and acceptors—against published limits. This is not a prediction of activity: it describes where the molecule stands against four limits.
Take it with you: SVG (RDKit’s drawing), PNG (the screen as it is), Compartilhar (Share: copies the public-page link, § 8).
Theme: light, dark, or system.

Panel footer, translated: “Calculated by RDKit… No number on this screen passes through a language model.”

5. Stereochemistry

With the W tool, click a bond: solid wedge; again, hashed wedge; again, none. RDKit assigns R or S by reading the wedges—the letter appears next to the atom in both the drawing and the scene. A center without a wedge appears with ?, and under Identity as sem configuração (unspecified configuration). Double bonds receive E or Z.

When you clean up a drawing containing wedges, the top banner explains what happened to each one: a wedge that did not define any configuration (the atom was not a stereogenic center) disappears, and the banner explains why; a wedge at a true center may become a hashed wedge when the atom moves to the other side of the paper—the same configuration, so the letter stays the same.

Solid and hashed wedges survive SMILES (F[C@H](https://github.com/GabrielMello1407/Rotamer/blob/main/docs/Cl)Br) and the public page.

6. The 3D scene

As soon as the structure is valid, the molecule starts tangled and folds into its lowest-energy shape—these are actual minimization frames from the MMFF94 force field—and then vibrates, through molecular dynamics at 300 K. A single bond rotates; a double bond does not.

Controls: rotate with the mouse or a finger; show or hide hydrogens; display the volume; recenter; enlarge (the scene grows to half the workbench while the drawing stays beside it). Touching an atom in the drawing lights it up in the scene, and vice versa. Double and triple bonds appear as parallel sticks.

For an element MMFF94 does not parameterize (the panel identifies it), the shape still appears, assembled from bond lengths and angles—what is unavailable is energy, and without energy there are no vibrations or normal modes.

With “reduce motion” enabled in the system, folding and vibration are disabled and the final geometry appears immediately.

7. Missions

Open Missões (Missions) in the top bar. The Escolher missão (Choose a mission) selector lists the catalog by track—Structure, Geometry, Property—and Sem missão — ferramenta livre (No mission—free tool), the mode without a storyline: “Draw whatever you like. Descriptors still come from RDKit with every stroke.”

Each mission has instructions, objectives checked off as you meet them, and a score from 0 to 100, proportional to the objectives completed. The verdict comes from the mission engine comparing RDKit’s calculated numbers—never from a language model. Ver dica (See hint) shows one hint at a time; they are handwritten and only appear when requested.

When all objectives are met, cumprida (completed) appears. With an account, progress is saved—“Progress saved. Score checked on the server: 100 out of 100.”—and the mission gains a ✓ in the selector. Without an account, the screen invites you to Entre na sua conta (Sign in to your account) to save what you have completed.

The tutor lives in the same panel, with three questions: E agora? (What next?), Por que não fechou? (Why didn’t it work?), O que é isto? (What is this?). It only accepts a question once there is a valid molecule. The answer is marked in amber and includes the message, translated: “Text generated by a language model from calculated numbers. It is a hypothesis, not a measurement.” The numbers in the text are RDKit’s calculations, inserted by the interface. On an instance without a Gemini key, it says it is disabled and directs you back to the handwritten hints. There is a daily question limit.

8. A molecule’s public page

Compartilhar (Share) copies a /m/<smiles> link that opens anywhere, without an account or JavaScript: formula, mass, descriptors, groups, RDKit’s drawing, and the nickname (§ 10), if there is one. Pasted into a WhatsApp group, the link includes an image and title. Abrir esta molécula no editor (Open this molecule in the editor) brings the drawing back.

9. Account and shelf

Entrar (Sign in), in the top bar, leads to /entrar: sign in with email and password, or create an account with your preferred name, email, password (8 characters or more), and school or institution—optional, but needed to follow the class later. Creating an account takes you straight back to the workbench, already signed in.

The account stores your mission progress and saved molecules. Sair (Sign out) clears the screen and draft: the lab computer is shared, and the next person to sit down will not find your molecule.

Save (Guardar), in the top bar, puts the structure in Minhas moléculas (My molecules). Saving the same structure twice still leaves just one row. Each row shows formula, mass, and date; opens in the editor; and has Página pública (Public page) and Tirar da estante (Remove from shelf, with confirmation in the row itself). What is saved is the graph: formula, mass, and descriptors are recalculated whenever the molecule opens.

Without an account, the draft stays in the browser and returns when you reopen it—and a link containing a molecule takes precedence over the draft.

10. Giving a structure a nickname

In the Análise (Analysis) panel, a structure no one has named can receive a nickname from the person who drew it: Dar um apelido (Give a nickname) → Batizar (Name it). The nickname belongs to the structure, applies to everyone on this instance, and never appears without the name of its author—“Ana’s molecule · named by Teacher Ana”—in the panel, public page, and shelf. Naming it also saves the structure in Minhas moléculas (My molecules).

What giving a nickname is not: nomenclature. “Rotamer chose not to name compounds: naming tools write in English, and translating a compound name means deciding its structure.” The screen therefore rejects a nickname that passes itself off as a systematic name (butanol) or formula (C9H8O4), and explains why.

Before offering a nickname, the product asks PubChem whether the compound already exists there. Known compounds cannot receive a nickname: the screen shows PubChem’s recorded name and CID. If PubChem does not respond, naming remains possible, with a notice that the check failed.

11. Classes—for students

Turmas (Classes) is at the top of the screen, beside your name. Enter the six-character code the teacher wrote on the board and choose Entrar na turma (Join the class). Until you have joined a class, the mission panel says so and provides the Entrar numa turma (Join a class) link. There is no email invitation. “The teacher sees which missions you have completed and where you stopped. What you draw outside missions is yours and is not shown to anyone.”

After that, the Missões (Missions) panel gains the DA SUA TURMA (FROM YOUR CLASS) section above the catalog: the assignment published by the teacher, in their order, with 0 de 5 cumpridas (0 of 5 completed). Any item opens in any order—nothing is locked. A teacher-written mission carries missão do seu professor (your teacher’s mission) and its authorship. Completing one shows Cumprida. Faltam 2 na lista. (Completed. 2 left in the assignment) and Próxima: … → (Next: … →); the last shows Cumprida. Você fechou a lista «…». (Completed. You finished the assignment “…”).

The Catalog (/catalogo, in the account menu) lists everything available to do—the product’s missions and those published by teachers—with search by name, track, or functional group («éster», «anel»…—“ester”, “ring”…). A teacher mission shows its author (missão de Professora Ana · EE Dom Pedro II—mission by Teacher Ana · EE Dom Pedro II) and a Denunciar (Report) option, with a one-line reason.

Forgot your password? At /entrar, Trocar com o código do professor (Change it with the teacher’s code) leads to /senha: account email, the eight-character code handed to you by the teacher, and a new password. The code lasts one day and can be used once; changing the password ends previous sessions.

12. Classes—for teachers

Becoming a teacher. No one declares themselves a teacher: anyone who can issue a password reset code can enter a student’s account. Create an account with the school filled in and request promotion using its email—from the person who administers your school’s Rotamer, who promotes through the interface, or from whoever installed the instance, who promotes with a server command (docs/INSTALACAO.md, “The first administrator”). The screen itself explains this: under Turmas (Classes), anyone who is not yet a teacher sees “Dá aula e quer abrir uma turma?” (Do you teach and want to create a class?), with the steps to follow. After promotion, Turmas que você dá (Classes you teach) appears on the next page you open—no need to sign out and back in.

Promoting the school’s teachers. If your account is an administrator, Turmas (Classes) has a Professores da escola (School teachers) section: teachers, their names and emails, who granted their role and when, plus an email field. Conferir (Check) shows the name of the person with that email, and only then displays Promover a professor (Promote to teacher). This step catches typos, because promoting the wrong account gives someone the power to issue a student’s password reset code.

An administrator can promote only as far as teacher, and only accounts from the same school, already filled in on both sides. Another administrator can only be created from the terminal by the installation’s operator: this ensures that a compromised account cannot take control of the instance. The screen never writes anyone’s school—an account created without that field must be promoted from the terminal with --escola. An account at another school gets the same rejection as an email that does not exist: the screen cannot be used to discover who has a Rotamer account.

Demoting. Beside each teacher, Rebaixar (Demote) returns the account to student status. What it loses: creating classes, building assignments, viewing the class board, and issuing password codes; its published missions also leave the catalog. What is kept: classes and assignments, restored in full if the account is promoted again. An account that has ever taught can only recover its password through the terminal, even after demotion—otherwise, demotion would become the first step toward entering a teacher’s account.

Creating the class. At /turmas, Turmas que você dá (Classes you teach) → name (3º A — manhã, class 3A—morning) → Abrir turma (Create class). The response includes the code: “Class ‘3º A — manhã’ created. The code is K7M2QX.” Write it on the board. The list shows how many students have joined.

The class board (click its name): the summary (“12 students, out of 15 missions in the catalog”), class assignments, a board for each published assignment, Onde a turma travou (Where the class got stuck)—missions where the most people tried without completing them, providing the basis for the next lesson—and Aluno a aluno (Student by student): who, completed, stuck on, last seen. “Stuck means having tried without completing—anyone who has not even opened the mission does not count here.” No student molecule appears on this screen.

Building an assignment. Nova lista (New assignment) → name (Funções oxigenadas — 3ª série, Oxygen-containing functional groups—3rd year). Within the assignment:

Escolher do catálogo (Choose from catalog): select missions by track and choose Acrescentar (n) (Add (n)).
Criar missão desenhando (Create a mission by drawing): the workbench opens with Criando missão · <lista> (Creating mission · ) and the Autoria (Authoring) tab. Draw the answer; the panel shows its formula with the calculado (calculated) badge and the objectives you can assess, extracted from the molecule—the formula, exact molecule, each functional group, each atom count, and each descriptor count. Select what you want to assess. Write Título da missão (Mission title), Enunciado (Instructions: “Talk about chemistry, not the interface”; no links; no student names), and up to three Dicas (Hints), one at a time. Salvar missão (Save mission) adds the mission to the assignment: “‘The everyday alcohol’ was added to the assignment at position 2.”

Selecting é exatamente esta molécula (is exactly this molecule) disables the other objectives—“The score becomes 0 or 100 and a similar isomer earns nothing. To accept more than one correct answer, assess groups and counts instead.” You cannot write an objective: “what the student must achieve is always what RDKit measured here”. A mission whose own answer fails an objective is rejected, identifying that objective. The answer is stored inside the mission, and the student never receives it.
Order: Subir (Move up), Descer (Move down), Remover (Remove, with Desfazer—Undo—for a few seconds).
Publicar para a turma (Publish to class): from then on the class sees the assignment, and the objectives of your missions are locked—changing an objective would change the scores of people who already tried. Titles, instructions, and hints remain editable.
Publicar no catálogo / Retirar do catálogo (Publish to catalog / Remove from catalog), mission by mission: once published, any account on the instance can find it through search, with your name and school. Requires a school to be filled in. Removal ends access through the catalog; students arriving through their own class assignment retain access.
Arquivar lista (Archive assignment) removes it from both screens without deleting anything; Desarquivar (Unarchive) brings it back.

The assignment board: one row per student, one column per item, with ✓ cumpriu · • travou (abriu e não cumpriu) · – não abriu (✓ completed · • stuck [opened but not completed] · – not opened), cumpridas (completed, 3 / 5), and última vez (last seen). Above it, ONDE A TURMA TRAVOU NESTA LISTA (WHERE THE CLASS GOT STUCK IN THIS ASSIGNMENT).

Password codes. The Códigos de senha (Password codes) link appears in two places you already visit: the Turmas que você dá (Classes you teach) section under Turmas (Classes), and the top of each class page. Inside: the email of the person who lost their password → Emitir código (Issue code). The code appears once—write it down and hand it over in person. It lasts one day, works once, and is only for someone at the same school as you. Issuing another invalidates the previous one.

13. What Rotamer does not do

It does not predict reaction products or propose synthesis routes.
It does not claim biological activity. Descriptors are descriptors.
It does not calculate IUPAC names. It lets people give nicknames, which is different.
It does not replace PyMOL, ChemDraw, or Maestro.
Frequencies come from the force field, not measured spectra—and the screen says so.