The Birss App

Content: Public overview of the app: what it computes, how to run it, and where the science comes from. Status: living Authority: authoritative for the public description of the project.

Calculates non-zero susceptibility tensor components (Electric Dipole, Magnetic Dipole, Electric Quadrupole) and induced transverse Second Harmonic Generation (SHG) source terms for all 32 crystallographic and 122 magnetic point groups.

Live Demo

Features

• Calculator:
  • Automatic determination of non-zero and independent components for Electric Dipole (ED, $\chi^{(2)}$), Magnetic Dipole (MD), and Electric Quadrupole (EQ) tensors.
  • Supports Time-Reversal symmetry toggles (i-type, c-type).
  • Real-time calculation of induced nonlinear response in the Lab Frame ($S_X, S_Y, S_Z$) with incoming light propagating along the Z-axis ($E_Z = 0$).
• Explorer:
  • Browse all 122 magnetic point groups.
  • Filter by crystal system and group type (Ordinary, Gray, Black & White).
  • View symmetry operations and properties for each group.
• Simulator:
  • Visualize expected SHG intensity polarimetry patterns.
  • Adjust crystal orientation, tensor component amplitudes, and phases to simulate parallel and crossed polarization configurations.
  • Interactive radar charts displaying SHG intensity as the analyzer angle is rotated.
  • Mathematically simplified and summarized expanded formulas using harmonic Fourier series representation (power reduction and multiple-angle formulas).
  • Smart grouping algorithm to automatically pick the most elegant representation (power vs harmonic) and minimize unnecessary minus signs.
• Tables: interactive Birss-table lookup — any rank 0–4 tensor by spatial/time parity and intrinsic symmetry, rendered rank-specifically (matrix, Nye scheme, relation list) with the Birss lookup chain; print-anchored against the vendored tables 4a–4f.
• Global Birss | ITC symbol-convention toggle: relabels group symbols and standard settings app-wide (Explorer, search, Calculator, Simulator, Tables) — display only, computed output always follows the Birss engine conventions below.
• Help & Documentation:
  • Comprehensive physics background, mathematics behind the intensity calculations, and usage instructions.
• Birss Reference Tables:
  • The complete, transcribed reference tables from Birss, Symmetry and Magnetism (1966) ship in this repo under birss-tables/ — usable standalone, independent of the app.
  • Most tables are verified against the printed book (documented per-file changelogs and errata; Table 4f print-verified 2026-07-09); the app's tensor output is pinned to them by ~150 golden-fixture tests and a CI drift guard.

Conventions & References

The tensor component output follows the conventions of Birss, Symmetry and Magnetism (1966): the y-axis secondary convention for trigonal and hexagonal groups (σ(2)=[2_y], σ(4)=[-2_y]), and the z-unique monoclinic setting. The app's rank-3 polar tensor output has been verified against all 21 rows of Birss Table 4e; rank 0-4 forms are print-anchored against Tables 4b-4f and Table 7. Point group names use Hermann–Mauguin notation with ITC-style rendering (overbars for roto-inversions, primes for time-reversed operations).

• App convention references (this repo): the convention contract & verification ladder and the 122-group nomenclature table — how each group's key maps to its Schoenflies / full-HM / Shubnikov notation and to its Birss operators, generators, and tensor form (App↔Birss↔ITC divergences flagged; see Reference & Original Birss Sources below for the full table set).
• Birss, R. R. (1966). Symmetry and Magnetism: Authoritative source for magnetic point groups and tensor component calculation. Reference tables included in this repo under birss-tables/.
• International Tables for Crystallography: General crystal symmetry aspects. See BIRSS-ITC-CONVENTION-DIVERGENCES.md for a detailed comparison of Birss vs ITC conventions.
• Pershan, P. S. (1963). Nonlinear Optical Properties of Solids: Nonlinear optical multipole contributions.
• Fröhlich, D., et al. (1999). Nonlinear spectroscopy of antiferromagnetics: Source term calculation.

Reference & Original Birss Sources

Beyond the app itself, this repo provides the complete transcribed Birss (1966) reference tables and didactic guidance under birss-tables/. They serve a double role: a citable, standalone transcription of the printed tables (with documented errata and print-verification notes), and the verification anchor of the app — the audit chain printed book → transcribed tables → app output is enforced by table-anchored golden fixtures and a CI guard, so app results provably match a by-hand Birss derivation.

• The tables: table-3, table-4a–table-4f, table-6, table-7, table-nomenclature (regeneration guide — CI-enforced against table-6.md).
• conventions-reference.md — axes, nomenclature, bracketed settings, z∥c.
• birss-itc-comparison.md — divergences from the International Tables (S₆/C₃ᵢ, type numbering).
• The typeset birss-tables.pdf.

These are the same tables the app is built on — see birss-tables/README.md for the full index and how to use them.

Validation & Testing

The tensor-calculation engine (src/services/) is covered by a Vitest suite of 2,200+ tests. Filename suffixes encode the test classes (*.reference — re-parse the vendored tables at test time; *.audit — exhaustive coverage contracts; *.pins — engine-derived regression pins; *.interaction — jsdom UI layer), on top of the tiered scientific checks:

• Tier 1 — group order: for all 122 magnetic point groups, getSymmetryOperations returns a group of the expected order.
• Tier 1b — true closure: for all 122 groups, every pairwise product of elements in the closed group is itself a member, independently verifying the floating-point-hardened closure algorithm in symmetryGroups.ts.
• Tier 2 — parity invariants: for all 122 groups, structural invariants such as "ED vanishes for centrosymmetric groups", "EQ never vanishes", and "grey groups G1' reproduce G for i-type tensors".
• Tier 3 — golden component relations: 150+ fixtures pinning down the exact independent-component relations for specific (group, tensor type, time-reversal) combinations. Includes all 21 Birss Table 4e symbol classes (A3–U3) at rank 3, every Type-III crystal family, c-type ED (e.g. the canonical Cr₂O₃ -3'm' magnetoelectric tensor), axial (MD) tensors, and rank-4 EQ. See src/services/goldenTensors.fixtures.ts for sources and citations.

Tech Stack

• React 19 + Vite
• Tailwind CSS for styling
• Lucide React for iconography
• KaTeX (react-katex) for mathematical rendering
• Recharts for radar chart visualizations
• Framer Motion for smooth animations
• GitHub Actions for automated deployment to GitHub Pages

Running Locally

1. Clone the repo: git clone https://github.com/manganite/birss-app.git
2. Install dependencies: npm install
3. Start development server: npm run dev
4. Build for production: npm run build

Project History

This repository was originally bootstrapped from a Google AI Studio app export; the application has since been fully rewritten and no scaffold code remains.

Changelog

See CHANGELOG.md for release history.

License

This project is licensed under the MIT License.