validate_sym.m

Extended validation of user-declared permutation symmetry. Confirms that the Zeeman, coupling, and giant-spin interactions stored in the spin system object are strictly invariant under every operation of each declared permutation group, so that the irreducible representation projectors built by symmetry.m correspond to a symmetry that the interactions actually possess. The declared symmetry is a permutation of spin labels, not a spatial rotation; interaction tensors related by a rotation rather than being identical are not accepted. When no symmetry is declared, the function returns without performing any checks.

The function returns immediately when 'symmetry' is listed in sys.disable, and also when bas.sym_group is absent or empty. Otherwise it loops over the declared groups. All spins in a group must carry the same isotope, and an error is thrown when they do not. The elements of the group are obtained from perm_group.m and each of them is extended into a permutation of all spins in the system, acting as the identity outside the group. For every group element and every spin in the group, three tests are performed: the Zeeman matrices of the spin and of its image must coincide, the giant-spin coefficient arrays must have the same number of ranks and coincide rank by rank, and, for every spin in the system, the coupling tensor returned by get_coupling.m between the spin and that partner must coincide with the one between their images. Agreement is tested with the matrix 2-norm of the difference against the tolerance 2*pi*tols.inter_cutoff, that is, the interaction cutoff tolerance expressed in rad/s. Each failed test raises an error naming the group and the offending spins. When every test passes, a confirmation line is printed through report.m.

Syntax

    validate_sym(spin_system,bas)

Parameters

    spin_system  - Spinach spin system description object, with the
                   interaction arrays already processed by create.m

    bas          - basis specification structure; the fields used
                   here are bas.sym_group (cell array of group names)
                   and bas.sym_spins (cell array of spin index vec-
                   tors), as described in the basis specification
                   section of the online manual

Outputs

    this function returns nothing; it throws a descriptive error when
    the interaction data does not obey a declared symmetry

Notes

This is a service function of the Spinach kernel that should not be called directly; it is called by symmetry.m.

The consistency check also requires bas.sym_spins to be present whenever bas.sym_group is given, both to be cell arrays of the same length, and every entry of bas.sym_spins to contain at least two valid spin numbers.

See also

symmetry.m, perm_group.m, get_coupling.m, summary_symmetry.m, create.m, report.m, Kernel utilities

Version 2.13, authors: Ilya Kuprov