How Caustica works

Caustica is a tool for easily visualizing strong gravitational lensing, named after the term used by 17th century mathematicians for the curves onto which refracted light rays converge, which were capable of burning objects.

Quick start

On a computer the window has three parts: the image with a strip of view controls above it, the scene drawer below the image, and the control panels on the right, chosen with a column of icons along the right edge. Phones use a single scrolling column instead, with a redshift timeline and a plane viewer for the scene; the phone way of doing each step is given after the computer one.

1. Add a plane with + Plane in the drawer’s header, which puts an empty plane behind the farthest one. The strip beside it is your line of sight: it runs from the observer (the eye at its left, which shows or hides the observation’s card) out in redshift, ending at z_max, which you set in the box at its right end (type a value, or drag sideways on the box to scrub; it never goes below the farthest plane, and placing a plane beyond it raises it), with a mark for each plane at its z (the selected plane’s mark is ringed). Marks that would overlap step into a lane just above or below the line, with a short stem down to their redshift, so planes at nearly or exactly the same z can each still be seen, clicked and dragged. Drag a mark to move its plane in z, or click it to select that plane; pointing at a mark lights up its card, and pointing at a card lights up its mark. Click a blank stretch of the strip to add a plane at that redshift: pointing there shows a dashed mark with the z it would get. A thin line labelled z_s marks the reference source redshift the critical curves and caustics are drawn for (§4), dashed while it is on Auto; drag it to set a custom value, or double-click it to go back to Auto. Below the strip, each plane is a card, in order of redshift, and clicking a card selects its plane. The chevron at the right of the header (or the handle at the top of the drawer) tucks the drawer away to give the image more room. On phones, tap the redshift timeline under the image to add a plane at that redshift; plane markers sit on the axis (stacking upward only when they would overlap), drag one to move it and tap one to select it, and the z_max field at the axis’s right end sets its range.
2. Pick a creation tool from the thin column of buttons at the left of the window: each button is the shape of that object’s marker: ▲ for a Lens (deflects light), ▼ for a Source (emits light), and ◆ for a Hybrid (both at once, shown as a purple diamond), or keys 1 / 2 / 3. An armed button lights in the colour of what it places. There is no separate select tool: click the highlighted letter again (or press Esc) to switch it off, and with no tool active a click only selects and drags, so you can move objects around without risking creating a new one. The trash button at the bottom of the column deletes the selected object. The tools and the ruler (§1) take turns: arming one switches the other off.
3. Click to place an object of the chosen type: in a card’s viewer, which places it on that plane (and selects the plane), or on the main image, which places it on the selected plane; a small label beside the pointer over the image names the object and the redshift it will land at. Both put it at the same sky position, since a viewer shows its plane’s true (unlensed) positions over the same field as the image. Drag to fine-tune, either in a viewer or on the image. Every card shows its viewer and redshift, and the selected one is outlined in its plane’s colour. A press on another card’s viewer selects that plane (placing there at once if a tool is active, or picking up the object under the pointer, so one press can select a plane and drag one of its objects). A plain click on empty space in the image clears the object selection but keeps the plane selected; deleting the selected plane selects the next one. The selected plane’s controls sit in a panel at the right end of the drawer, under its type: the Redshift box (type a value, or drag sideways on it to scrub; the cards and the strip re-sort as it changes), and Clear (key O) and Delete (key X). They stay in that one place whichever plane is selected, so selecting a plane never moves the cards. The [ / ] keys step the selection through the planes. While there is an observation (§7), the tool column also has a mask button (key 4); masks belong to the observation, and are placed on the image or on the observation’s card at the left end of the drawer (shown by clicking the strip’s eye). On phones the Scene tab holds a plane viewer for the selected plane, the only place objects are created there: its L / S / H tools (plus M while there is an observation) and a trash button run down its left side, the ‹ › arrows (or a horizontal swipe not starting on an object) step through the planes, and a Redshift box sits at the top right, with Clear and Delete buttons under a “Plane:” heading at the bottom right. Selecting several objects. On a computer, Cmd-click (Ctrl-click on Windows and Linux) adds an object to the selection or takes it out, in the image or in a card’s viewer, and dragging across empty space in the image draws a box that selects every object inside it (hold Cmd/Ctrl to add the box to the selection). Dragging any selected object then moves them all by the same offset, across planes too. Only moving is shared: the Object panel, Delete and every other edit act on the object clicked last, which the panel notes while several are selected. A click on one member without dragging keeps just that one, a click on empty space clears the selection, and Esc returns to a single object.
4. Adjust parameters in the Object panel (the triangle at the top of the right-hand icons; the Object tab on phones). Switching an object’s model keeps its position and whatever the two models share: the axis ratio $q$, the position angle $\varphi$, the deflection scale $b$ of the mass models, and a source’s colour; the rest start at the new model’s defaults, and a value the new model lacks (a point mass has no $q$ or $\varphi$) comes back when you switch to one that has it. For hybrid objects, separate collapsible sections appear for the lens and source halves, each with its own show/hide (eye) and delete buttons, so a single half can be toggled or removed while the other stays. The eye button excludes an object from the computation without deleting it: it stays as a grey marker, on the image and in its plane’s viewer, where it can still be selected, moved and shown again. Copy the selected object with Cmd/Ctrl+C and paste a duplicate in the same place with Cmd/Ctrl+V. Scene edits (adding, moving, deleting, and adjusting objects and planes) can be reversed with the undo/redo arrows to the right of the title (or Cmd/Ctrl+Z and Cmd/Ctrl+Shift+Z); view settings such as field of view and colour mapping are not part of the undo history.
5. The image panel updates in real time. On a computer each view is a tab in the strip above the image. Click the showing tab to change its view from a menu, + adds another view as a tab, and the letter keys switch the current tab’s view (I for the lensed image, see the shortcuts below). The menus group the views by the plane they show: the image plane (the sky as observed: the lensed image and the quantity maps) or the source plane (the Image number and Delensed image views). A source-plane view says so with a source tag on its tab. To see two views side by side, use the split button at the end of the strip, which opens an empty pane offering the views, or drag a tab onto the right half of the image; tabs can then be dragged between the two strips. Both panes react to the same edits (objects can be placed and dragged in either), and clicking one makes it the view that the panels on the right and the shortcuts act on. The showing tab and its image share one outline, like a folder tab; beside another view, the focused one is marked by a teal line along the top of its tab. The link button between the two views chooses what they share: zoom, the reference source redshift, the display toggles (legend, scale bar, object shapes, colorbar, stretch, time delays), the instrument, line art, and the background framing. All are shared at first; switching one off gives each view its own copy, starting from the current setting, so for example the two views can be zoomed separately or show two instruments side by side, and switching it back on gives both views the focused one’s setting. Color maps are set per kind of view in any case. Exports (§10) capture the left pane. Each view has its own critical-curve, caustic and marker toggles at the right end of its tab strip, so curves can sit on a quantity map while the lensed image beside it stays clean; C toggles the curves and caustics of the focused view (on phones the toggles are chips on the image, under the view menu that stands in for the tabs). Zoom with the mouse wheel or a two-finger pinch; the scale bar at the bottom right of the image tracks the angular scale as you zoom (1″, 2″, 5″, or 10″ depending on the field of view), and the Field section of the View panel accepts an exact FOV value. On touch screens, a horizontal swipe across empty image space cycles the displayed view (the lensed image and each quantity map, wrapping around); vertical swipes still scroll the page, and touching an object still drags it. The Hide all overlays switch in the View panel blanks the labelling annotations (position markers, legend, ruler, scale bar) and the on-canvas controls for a clean plot until switched back; critical curves and caustics stay, since they are lensing structure rather than labels (toggle those off separately if you want them gone). Use the Export tab to save a PNG, WebM, or GIF.
6. Measure angular distances with the ruler. Its button is at the bottom of the tool column at the left, below the object tools and their delete button, after a short line (on phones, at the bottom-left of the image panel); click it or press L to arm it, and again to disarm it. The Rulers toggle in the View panel’s Display section shows or hides the measurements. With the ruler armed, click and drag on the image between two points: a line appears with its separation in arcseconds and position angle (e.g. 1.42″ · 34°). Each new measurement becomes the selected item, and measurements are editable: click one to select it, drag its line to move it, or drag an endpoint to reshape it. Delete the selected measurement with a trash button (the tool column’s also deletes measurements) or Backspace; clear all of them with the × button on the image. Measurements persist when you disarm the ruler. The measurement lines are captured in saved PNGs and recordings; the ruler buttons themselves are not.
7. Save and load configurations using the Save / Load buttons in the top bar, next to the preset dropdown (on phones they move into the top bar’s ⋯ overflow menu, which also holds Docs, Tour, the shortcut reference, and the theme toggle, keeping undo / redo and presets on a single row). The file stores all planes, objects, and parameters along with the full view state, so a loaded config reproduces the same picture: field of view, active quantity, per-quantity color mapping, contour spacing, the critical-curve resolution, point-source grid density, and render scale, and the overlay and ruler toggles. Any setting absent from a file loads at its default value.

Full screen. The button beside the theme toggle (key F) shows only the image, or both views side by side, at the largest size the window allows: the top bar, tool column, scene drawer, panels and tab strips go, while the legend, scale bar and other on-image overlays stay, and objects can still be dragged. It also takes the browser to full screen where it allows that. F, Esc, or the faint button in the top-right corner leaves it. Any armed placement tool or the ruler is switched off on the way in.

Saving. Save downloads the scene as a YAML config, and Load reads one back: the planes and objects, the view settings, the observation’s settings and masks, and the layout of the views (which tabs are open in each pane, which is focused, which settings are unlinked between them). A picture you upload yourself is not saved in it. The Presets menu holds ready-made scenes (§11).

Where the controls live. On a computer the icons down the right edge pick what the panel beside them shows: Object (the selected object’s parameters), View (the Field section with the field of view and the reference source redshift, Hide all overlays, the Display toggles (among them Shapes, which shows or hides, in that view, the dashed outlines of the objects whose own Show shape is on), the Critical curves display options, and the settings of the active view, such as Fermat contours or Image number spacing), Colors (the Color map of the active view, the Field color, the Annotations ink, and the Line art switch, which shows its options, palette and colors while it is on), Background (a decorative picture behind the image, framed to the panel), Observation (the eye: the observed image of a lens on the sky at its pixel scale, its masks, and the way into the Delensed image view), Instrument, Export, and, at the bottom, the gear for Settings (cosmology and quality). On a computer every section is shown open. On phones the tab bar has Object, Scene, View, Export, and a gear for Settings, and the View tab lists the View, Colors, Background, Observation and Instrument sections one after another, some of them collapsible. Where these docs say “the View tab”, it means that list on a phone and the matching panel on a computer.