Keyboard controls

Use ↑ / ↓ to move between controls and ← / → to change the focused option or value. In text fields, ← / → moves the cursor. Enter or Space activates buttons; Escape closes dialogs. Tab and Shift+Tab also move focus.

Start with the tutorial

Click Guided tour for step-by-step chapters. Each chapter restarts the app and highlights the relevant controls:

1. Upload a structure and define its moments — import a CIF, enter magnetic moments in the crystal basis, and determine the magnetic space group with FINDSYM.
2. Read the tensors, the multipoles and their ordering — compare Channel and Irreducible decompositions, inspect symmetry groups, and switch between Full ℳ, Ordinary 𝒩 and Toroidal 𝔗.
3. Moment, SOC and system — explore magnetic ℳ and electric 𝒟 moments, spin-orbit coupling, and system-level symmetry.
4. Multipole visualizer — ranks, M channels and the tensor-parameter sliders of the 3D panel.
5. Moment visualizer — adjust a symmetry-allowed vector field, inspect a 2D slice, and export a PNG.

Follow the chapters in order or jump to the topic you need. The conventions and reference details are below.

Conventions

• Conventional crystallographic basis: Tensor entries, axes, and viewer face labels follow the conventional setting of the International Tables for Crystallography, not a pseudocubic basis. Symbolic tensor entries do not include metric-dependent cell-length factors.
• Cell parameters affect geometry: They set the 3D cell, atom positions, distances, and isosurfaces without changing symbolic tensor entries.
• Voigt index convention: 11 → 1, 22 → 2, 33 → 3, 23,32 → 4, 13,31 → 5, and 12,21 → 6. The app follows Bilbao-style index abbreviation for rank 3 to rank 5 tables: symmetric spatial index pairs are abbreviated as Voigt labels, and mixed pairs are not multiplied by engineering factors.
• Higher-rank Voigt layout: The first reduced index labels the rows; the remaining reduced indices label the columns. Non-channel tensors use [V3] → [voigt, single] as a 6 × 3 table, [V4] → [voigt, voigt] as a 6 × 6 table, and [V5] → [voigt, voigt, single] as a 6 × 18 table. Magnetic, electric-toroidal, and magnetic-toroidal tensors keep the final M, G, or T channel explicit: rank 3 is [voigt, channel] (6 × 3), rank 4 is [voigt, single, channel] (6 × 9), and rank 5 is [voigt, voigt, channel] (6 × 18).
• Colors identify independent parameters: The same parameter has the same color in tensor entries and expressions.

1. Choose the structure

Choose a group, load an example, or import a structure.

• BNS input: Type a magnetic space-group number such as 1.1 or 62.448. The group selector is updated automatically.
• Group selector: Choose the magnetic space group directly from the dropdown.
• Example: Load a bundled material from the dropdown.
• Import: mCIF files are read directly; regular CIF files are symmetrized with FINDSYM.

2. CIF and mCIF import

• mCIF: Reads the magnetic group, atom coordinates, and magnetic atom labels, plus Wyckoff labels and cell parameters when available.
• Regular CIF: FINDSYM determines the magnetic space group. If moments are missing, enter m_a, m_b, and m_c in the uploaded CIF crystal basis.
• FINDSYM citation: Provided in the import window.
• Missing or incompatible cell parameters: Tensors are still computed; the viewer uses ideal geometry when needed.

3. Choose Wyckoff or System

• Wyckoff position: Computes site-specific tensors and atom ordering for one crystallographic orbit.
• System: Uses the full space-group symmetry and, for imported structures, the occupied or magnetic sites when available. The ordering panel shows a common list for the system.
• Magnetic System without SOC: Select the magnetic Wyckoff sites if the file does not identify them.

The calculation starts automatically after selecting a Wyckoff position or System.

4. Type, moment sectors, and SOC

• Type: Choose Electric or Magnetic in the header.
• Parent moment: 𝒟 for Electric; ℳ for Magnetic.
• Displayed part: Full shows the complete parent moment; Ordinary and Toroidal select its projected sectors. Which sectors are offered depends on the current view.
• Electric sectors: D^(k) is the full polarization moment, Q^(k) its fully symmetric charge sector, and G^(k-1) its first-dual toroidal sector.
• Magnetic sectors: M^(k) is the full magnetization moment, N^(k) its fully symmetric magnetic-charge sector, and T^(k-1) its first-dual toroidal sector.
• Toroidal naming: Every symmetric-traceless multipole of the first-dual r × μ tensor keeps the magnetic-toroidal name T_ℓm, including lower-rank sectors obtained after taking traces. H_ℓm is reserved for an explicitly computed second-dual r × (r × μ) sector. Changing the displayed field does not rename a multipole.
• SOC: Includes spin-orbit coupling in the magnetic symmetry analysis.
• Toroidal set: For magnetic toroidal tensors, Dualized uses the allowed parent magnetic tensors; Neumann allowed solves the toroidal symmetry constraints directly.
• Shorthand Notation: Compacts rank 3–5 tensors by abbreviating symmetric spatial pairs from left to right. Lower ranks are unchanged. Channel tensors keep Mx/My/Mz, Gx/Gy/Gz, or Tx/Ty/Tz as the final explicit channel.

5. Tensor results

• Symmetry operations: Shows the operations used for the selected site or whole system.
• Tensor matrices: Show all symmetry-allowed tensor entries. Zero entries are forbidden by symmetry. Repeated colored labels are the same independent parameter.
• Expression labels: Show relations between entries using the same parameter colors.
• Rank decomposition: Rank-2 controls separate trace, antisymmetric, and symmetric-traceless parts. Higher ranks show the computed irreducible components.
• Numerical precision: Very small coefficients are displayed as zero to suppress rounding noise.
• Toroidal monopoles: A notice identifies symmetry-allowed electric G₀ and magnetic T₀ channels. It does not establish a nonzero amplitude.

6. Atom ordering

• Ordering block: Compares the tensor or multipole on atoms in the orbit with the representative atom.
• UP / DOWN / NCL: UP means parallel to the reference atom, DOWN means antiparallel, and NCL means non-collinear or not comparable by a simple sign.
• Groups: Atoms whose tensors behave equivalently share a group. Green means parallel behavior, red means antiparallel behavior, and neutral means mixed or non-collinear.

7. Site multipoles

• The Site Multipoles tab expands the density on the selected site into multipoles. With System selected it expands the density of the whole cell instead.
• Channel components: Expand each Cartesian component of the magnetization (or polarization) separately in spherical harmonics. A label Y_ℓmM_x is a degree-ℓ harmonic carried by the M_x component.
• Irreducible multipoles: Couple the spatial and vector indices into states of definite total angular momentum J.
• Trace Free / Trace Full: Trace Free keeps only the leading channel, ℓ = k−1. Trace Full adds the lower-ℓ trace sectors at the same tensor rank, each carrying a radial factor r^k−1−ℓ.
• Expansion of (Electric only): Charge ρ expands the scalar charge density and needs no vector channel; Polarization P expands the polarization density.
• Parent tensor box: Shows the integral the multipoles are taken from, and the region it runs over.

8. Ordering of multipoles

• Use the Ordering of Multipoles tab to see which real harmonics order ferroically or antiferroically.
• Multipoles: Channel expands the spatial dependence of each tensor channel separately. Irreducible couples all indices into total-J multipoles.
• For a selected Wyckoff site, both Ferro and Anti-Ferro lists are shown when present.
• System: Shows the symmetry-allowed system multipoles in the global frame, without site-orbit Ferro/Anti-Ferro labels.
• Magnetic ordering: Uses the full parent moment. In Irreducible mode, each allowed physical (J,m) multipole is listed once with labels such as M₀ and M_xy, rather than repeated under parent tensor ranks.
• Export LaTeX downloads the current ordering table as LaTeX code.

9. Multipole visualizer and spherical harmonics

• Rank: Selects the rank to display. Available ranks depend on the mode.
• Multipoles: Sliders build a linear combination of allowed real spherical harmonics for the selected rank.
• Displayed part: Choose Full, Ordinary, or Toroidal where available. Full includes the parent tensor's trace and mixed-symmetry components; Irreducible mode offers Ordinary and Toroidal.
• Displayed field: Switch between μ, r × μ, and r × (r × μ), or their electric counterparts with P. Coefficients stay in the original parent tensor; each dual reduces the displayed tensor rank by one.
• Frame: Harmonics, channels (Mx, My, Mz) and their Ferro / Anti-Ferro labels are written in the frame chosen in the header, the same frame used by every other view. When it differs from the crystal axes, the Frame switch shows its x, y, z axes at each atom.
• Resolution: Fast reduces rendering cost; Ultra gives smoother surfaces. High is the default.
• View: Faces the camera toward the selected crystallographic plane.
• Rotation: The speed slider is in revolutions per second, up to 2 rev/s.
• Export PNG: Saves the current 3D view.

10. Moment visualizer (vector field)

• Switch the visualizer to Vector Field to draw a symmetry-allowed field built from the selected coefficients. It is one field consistent with the symmetry, not a computed physical field.
• Moment tensor rank, Moment density, Moment tensor: Choose the rank, whether the field represents magnetization μ or polarization P, and which sector supplies the coefficients.
• SOC: Selects the SOC or SOCless tensor space for the magnetic field.
• Field detail: Sets the sampling density and the number of arrows drawn, from Overview to Maximum.
• Multipole coefficients: One slider per symmetry-allowed control. Reset all to 0 clears them.
• Displayed field: Changes only what is drawn; the coefficients stay in the original tensor space.
• 2D slice: Show plane draws a cut through the cell; azimuth, tilt and offset move it. Color shows the direction of the field and opacity its magnitude.
• Atoms: Click an atom to show its field alone, without other atoms or periodic images. Click it again, or click empty space, to restore the total field.
• Appearance: Arrow threshold, arrow thickness, tip size, cell thickness, and field of view.

11. Reports and exports

• Export report: Available after uploading a CIF/mCIF. It summarizes filled Wyckoff positions and orbit ordering in a PDF report.
• Export LaTeX: Available in the Ordering of Multipoles panel once ordering data has been computed.
• Export PNG: Saves the current 3D view.