Hall to IT standard transform

Property name: Hall to IT standard transform
Description: Exact basis and origin transform from one stored Hall setting to the International Tables standard Hall setting of the same space-group type.
Type: dictionary
This transform is useful when data generated or detected in an arbitrary Hall setting needs to be compared with a conventional IT-standard reference setting. The transform is represented by matrix and vector, following the same affine-transformation convention as the other generated transformation tables.
If x_to_ref_hall is a fractional coordinate column vector in the target IT-standard Hall setting, and x_from_hall is the corresponding fractional coordinate column vector in the source Hall setting keyed by the containing map, then the stored transform satisfies: x_from_hall = matrix * x_to_ref_hall + vector.
Despite the source-to-standard purpose of the record, the stored affine map sends target-standard coordinates to source coordinates. To convert a source coordinate to the standard setting, evaluate matrix^-1 * (x_from_hall-vector). With cell basis vectors arranged as columns, B_standard = B_source * matrix. The transformed operation is W_standard = matrix^-1*W_source*matrix with translation matrix^-1*(W_source*vector + w_source - vector). Changing between centered and primitive descriptions can change the determinant without changing the group index.
{
    "$id": "https://schemas.httk.org/defs/v0.1/properties/transformations/hall_to_it_std_transform",
    "$schema": "https://schemas.optimade.org/meta/v1.3/optimade/property_definition.json",
    "title": "Hall to IT standard transform",
    "x-optimade-type": "dictionary",
    "x-optimade-definition": {
        "kind": "property",
        "version": "0.1.0",
        "format": "1.3",
        "name": "hall_to_it_std_transform",
        "label": "hall_to_it_std_transform_transformations"
    },
    "x-optimade-unit": "inapplicable",
    "type": [
        "object",
        "null"
    ],
    "description": "Exact basis and origin transform from one stored Hall setting to the International Tables standard Hall setting of the same space-group type.\n\nThis transform is useful when data generated or detected in an arbitrary Hall setting needs to be compared with a conventional IT-standard reference setting.\nThe transform is represented by `matrix` and `vector`, following the same affine-transformation convention as the other generated transformation tables.\n\nIf `x_to_ref_hall` is a fractional coordinate column vector in the target IT-standard Hall setting, and `x_from_hall` is the corresponding fractional coordinate column vector in the source Hall setting keyed by the containing map, then the stored transform satisfies:\n`x_from_hall = matrix * x_to_ref_hall + vector`.\n\n**Requirements/Conventions**:\n\n- It MUST be a dictionary describing one exact transform from the containing Hall setting to the IT-standard Hall setting of the same `it_number`.\n- The `index` value is always `1`, because this is a same-space-group setting transform rather than a proper subgroup transform.\n- Matrix and vector entries MUST be exact strings, using integer strings or fraction strings as appropriate.\n- It MUST be a dictionary with the following keys:\n\n    - **hall\\_entry**: REQUIRED; String.\n      Source Hall-entry key for the setting transformed by this object.\n\n    - **it\\_number**: REQUIRED; Integer.\n      International Tables space-group number shared by the source and target Hall settings.\n\n    - **to\\_hall\\_entry**: REQUIRED; String.\n      Target Hall-entry key for the IT-standard Hall setting of the same space-group type.\n\n    - **index**: REQUIRED; Integer.\n      Transform index.\n      For this table the value is `1` because the transform maps between settings of the same space group.\n\n    - **affine\\_transformation**: REQUIRED; Dictionary.\n      Exact affine map for this setting transform.\n      It MUST follow `/defs/v0.1/properties/symmetry/affine_transformation`.\n      The transform convention is `x_from_hall = matrix * x_to_ref_hall + vector`, where `matrix` and `vector` are the fields inside `affine_transformation`.\n\nDespite the source-to-standard purpose of the record, the stored affine map sends target-standard coordinates to source coordinates.\nTo convert a source coordinate to the standard setting, evaluate `matrix^-1 * (x_from_hall-vector)`.\nWith cell basis vectors arranged as columns, `B_standard = B_source * matrix`.\nThe transformed operation is `W_standard = matrix^-1*W_source*matrix` with translation `matrix^-1*(W_source*vector + w_source - vector)`.\nChanging between centered and primitive descriptions can change the determinant without changing the group index.",
    "properties": {
        "hall_entry": {
            "$id": "https://schemas.httk.org/defs/v0.1/properties/spacegroups/hall_entry",
            "title": "Hall entry",
            "x-optimade-type": "string",
            "x-optimade-definition": {
                "kind": "property",
                "version": "0.1.0",
                "format": "1.3",
                "name": "hall_entry",
                "label": "hall_entry_spacegroups"
            },
            "type": [
                "string",
                "null"
            ],
            "description": "Normalized Hall-table entry key used internally by the generated datasets.\n\nThe value is derived from the Hall symbol by using lowercase letters and underscores in place of spaces. It is stable for lookup within these data files, while the display Hall symbol is provided separately by `hall` and its formatted variants.\n\n**Requirements/Conventions**:\n\n- This field identifies a concrete Hall setting, not only an IT space-group type.\n- The same value is normally used as the key of the containing `spacegroups` map.\n\nThe normalization is `hall.strip().replace(\" \", \"_\").lower()`; signs, quotes, asterisks, and origin-shift notation are retained.\nThe key is a coordinate-setting identifier, not a numeric spglib Hall number.\nDifferent conventional H-M entry labels can resolve to the same Hall-entry record.",
            "x-optimade-unit": "inapplicable",
            "examples": [
                "p_1",
                "-p_1"
            ]
        },
        "it_number": {
            "$id": "https://schemas.httk.org/defs/v0.1/properties/spacegroups/it_number",
            "title": "International Tables space-group number",
            "x-optimade-type": "integer",
            "x-compatibility": [
                "https://schemas.optimade.org/defs/v1.2/properties/optimade/structures/space_group_it_number"
            ],
            "x-optimade-definition": {
                "kind": "property",
                "version": "0.1.0",
                "format": "1.3",
                "name": "it_number",
                "label": "it_number_spacegroups"
            },
            "type": [
                "integer",
                "null"
            ],
            "description": "The International Tables space-group number.\n\nThis integer identifies the space-group type numbered 1 through 230 in International Tables for Crystallography. Multiple Hall settings can share the same `it_number`.",
            "x-optimade-unit": "inapplicable",
            "examples": [
                1,
                5
            ]
        },
        "to_hall_entry": {
            "$id": "https://schemas.httk.org/defs/v0.1/properties/transformations/to_hall_entry",
            "title": "To Hall entry",
            "x-optimade-type": "string",
            "x-optimade-definition": {
                "kind": "property",
                "version": "0.1.0",
                "format": "1.3",
                "name": "to_hall_entry",
                "label": "to_hall_entry_transformations"
            },
            "type": [
                "string",
                "null"
            ],
            "description": "Target Hall-entry key to which a setting transform maps the current Hall setting.\n\nThe value is a normalized Hall-entry key following the same convention as `/defs/v0.1/properties/spacegroups/hall_entry`, i.e., derived from the Hall symbol by using lowercase letters and underscores in place of spaces.\nThe corresponding display Hall symbol can be recovered by looking up the key in the spacegroups dataset.",
            "x-optimade-unit": "inapplicable",
            "examples": [
                "p_1",
                "-p_1"
            ]
        },
        "index": {
            "$id": "https://schemas.httk.org/defs/v0.1/properties/transformations/index",
            "title": "Subgroup or transform index",
            "x-optimade-type": "integer",
            "x-optimade-definition": {
                "kind": "property",
                "version": "0.1.0",
                "format": "1.3",
                "name": "index",
                "label": "index_transformations"
            },
            "type": [
                "integer",
                "null"
            ],
            "description": "Subgroup or transform index.\n\nFor subgroup transforms it is the crystallographic subgroup index `[G:H]`, equal to the determinant factor of the basis transformation when applicable.\n\nFor the column-vector convention `x_G = P*x_H + p`, the exact index formula is `[G:H] = abs(det(P)) * n_symops(G) / n_symops(H)`.\nEquivalently it is the product of the translation index `i_T = abs(det(P))*n_centering_translations(G)/n_centering_translations(H)` and the point-group index `i_P = n_pointgroup_symops(G)/n_pointgroup_symops(H)`.\nThus a point-symmetry reduction can have index greater than one even when `det(P) = 1`.\nIn `hall_to_it_std_transform` the value is one even if the two cell conventions have different volumes; an ordinal index in another table must be interpreted as documented by that parent property.",
            "x-optimade-unit": "inapplicable",
            "examples": [
                2,
                4
            ]
        },
        "affine_transformation": {
            "$id": "https://schemas.httk.org/defs/v0.1/properties/symmetry/affine_transformation",
            "title": "Affine transformation",
            "x-optimade-type": "dictionary",
            "x-optimade-definition": {
                "kind": "property",
                "version": "0.1.0",
                "format": "1.3",
                "name": "affine_transformation",
                "label": "affine_transformation_symmetry"
            },
            "x-optimade-unit": "inapplicable",
            "type": [
                "object",
                "null"
            ],
            "description": "An affine transformation acting on fractional crystallographic coordinates.\n\nAn invertible affine transformation preserves collinearity and parallelism, but need not preserve Euclidean distances or angles.\nA singular affine map can collapse a line or plane to a lower-dimensional image.\nThe transformation is represented by a 3 by 3 matrix and a 3-vector, both serialized with exact string entries.\nWith column vectors, the map is `u_out = matrix * u_in + vector`; matrix rows specify the three output components.\nThe containing property identifies whether `u_in` denotes fractional coordinates or abstract Wyckoff parameters and identifies the input and output settings.\nNo wrapping modulo lattice translations is implicit in this equation; apply any required periodic reduction only in the specified output setting.\nThe transformation may, for example, represent an operation within one setting, a setting transform, a subgroup embedding, a normalizer representative, or a parametric coordinate map for a Wyckoff-position orbit representative.\nWhen used as a parametric coordinate map, the matrix may be singular because special Wyckoff positions can constrain or identify parameters.\n\n**Requirements/Conventions**:\n\n- It MUST be a dictionary with the following keys:\n\n    - **matrix**: REQUIRED; Exact 3x3 matrix.\n      Matrix part of the affine transformation.\n      It MUST be represented as a list of three row lists, each containing three exact rational entries represented as strings.\n\n    - **vector**: REQUIRED; List of 3 Fractions (String).\n      Translation or origin-shift vector of the affine transformation in fractional coordinates.\n\n    - **xyz**: OPTIONAL; String.\n      Coordinate expression for the affine transformation in `x,y,z` notation when available.\n      It MUST express the same affine map as `matrix` and `vector`, using `x,y,z` for the input components.\n\n    - **det**: OPTIONAL; Integer.\n      Determinant of `matrix` when the generator emits it.\n\n    - **is\\_orthogonal**: OPTIONAL; Boolean.\n      Whether the linear part preserves the crystallographic metric family specified by the containing setting; this is not a test of the fractional matrix against the Cartesian identity metric.",
            "properties": {
                "matrix": {
                    "x-optimade-type": "list",
                    "x-optimade-unit": "inapplicable",
                    "x-optimade-dimensions": {
                        "names": [
                            "dim_lattice",
                            "dim_lattice"
                        ],
                        "sizes": [
                            3,
                            3
                        ]
                    },
                    "type": [
                        "array",
                        "null"
                    ],
                    "description": "Exact 3 by 3 matrix part of the affine transformation.",
                    "items": {
                        "x-optimade-type": "list",
                        "x-optimade-unit": "inapplicable",
                        "x-optimade-dimensions": {
                            "names": [
                                "dim_lattice"
                            ],
                            "sizes": [
                                3
                            ]
                        },
                        "type": [
                            "array"
                        ],
                        "description": "One row of the exact 3 by 3 matrix.",
                        "items": {
                            "$id": "https://schemas.httk.org/defs/v0.1/properties/core/fraction",
                            "title": "Fraction",
                            "x-optimade-type": "string",
                            "x-optimade-definition": {
                                "label": "fraction_core",
                                "kind": "property",
                                "version": "0.1.0",
                                "format": "1.3",
                                "name": "fraction"
                            },
                            "type": [
                                "string",
                                "null"
                            ],
                            "description": "A numerical representation formed as the quotient of two numbers represented as a string.",
                            "examples": [
                                "2/3",
                                "5/42",
                                "10",
                                "0"
                            ],
                            "x-optimade-unit": "inapplicable"
                        }
                    }
                },
                "vector": {
                    "x-optimade-type": "list",
                    "x-optimade-unit": "inapplicable",
                    "x-optimade-dimensions": {
                        "names": [
                            "dim_lattice"
                        ],
                        "sizes": [
                            3
                        ]
                    },
                    "type": [
                        "array",
                        "null"
                    ],
                    "description": "Exact fractional-coordinate vector part of the affine transformation.",
                    "items": {
                        "$id": "https://schemas.httk.org/defs/v0.1/properties/core/fraction",
                        "title": "Fraction",
                        "x-optimade-type": "string",
                        "x-optimade-definition": {
                            "label": "fraction_core",
                            "kind": "property",
                            "version": "0.1.0",
                            "format": "1.3",
                            "name": "fraction"
                        },
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "A numerical representation formed as the quotient of two numbers represented as a string.",
                        "examples": [
                            "2/3",
                            "5/42",
                            "10",
                            "0"
                        ],
                        "x-optimade-unit": "inapplicable"
                    }
                },
                "xyz": {
                    "$id": "https://schemas.httk.org/defs/v0.1/properties/symmetry/op_xyz",
                    "title": "Operation xyz",
                    "x-optimade-type": "string",
                    "x-compatibility": [
                        "https://schemas.optimade.org/defs/v1.2/properties/optimade/common/symmetry_operation_xyz",
                        "https://www.iucr.org/__data/iucr/cifdic_html/2/cif_sym.dic/Ispace_group_symop.operation_xyz.html"
                    ],
                    "x-optimade-definition": {
                        "kind": "property",
                        "version": "0.1.0",
                        "format": "1.3",
                        "name": "op_xyz",
                        "label": "op_xyz_symmetry"
                    },
                    "x-optimade-unit": "inapplicable",
                    "type": [
                        "string",
                        "null"
                    ],
                    "description": "Coordinate operation expressed in the algebraic xyz form, also known as Jones' faithful representation (Bradley & Cracknell, 1972: pp. 35-37; adapted for computer strings).\n\nThe following definition is adapted from (and meant to be compatible with) the IUCr symCIF version 1.0.1 dictionary definition of `_space_group_symop.operation_xyz` referenced to: International Tables for Crystallography (2002). Volume A, Space-group symmetry, edited by Th. Hahn, 5th. ed. (Kluwer Academic Publishers).\nIt is available at: https://www.iucr.org/__data/iucr/cifdic_html/2/cif_sym.dic/Ispace_group_symop.operation_xyz.html\n\nIf W is a matrix representation of the rotational part of the symmetry operation defined by the positions and signs of x, y and z, and w is a column of translations defined by the fractions, an equivalent position X' is generated from a given position X by the equation: X' = WX + w.",
                    "x-undef-pattern": "^([-+]?[xyz]([-+][xyz])?([-+](1/2|[12]/3|[1-3]/4|[1-5]/6))?|[-+]?(1/2|[12]/3|[1-3]/4|[1-5]/6)([-+][xyz]([-+][xyz])?)?),([-+]?[xyz]([-+][xyz])?([-+](1/2|[12]/3|[1-3]/4|[1-5]/6))?|[-+]?(1/2|[12]/3|[1-3]/4|[1-5]/6)([-+][xyz]([-+][xyz])?)?),([-+]?[xyz]([-+][xyz])?([-+](1/2|[12]/3|[1-3]/4|[1-5]/6))?|[-+]?(1/2|[12]/3|[1-3]/4|[1-5]/6)([-+][xyz]([-+][xyz])?)?)$",
                    "examples": [
                        "-x,-y,z",
                        "x,1/2-y,1/2+z"
                    ]
                },
                "det": {
                    "x-optimade-type": "integer",
                    "x-optimade-unit": "inapplicable",
                    "type": [
                        "integer",
                        "null"
                    ],
                    "description": "Determinant of the matrix part when emitted by the generator.\nThis optional integer annotation MUST equal the exact determinant of `matrix`; its absence does not imply determinant one.\nRational matrices can have noninteger determinants, in which case this integer annotation is omitted."
                },
                "is_orthogonal": {
                    "x-optimade-type": "boolean",
                    "x-optimade-unit": "inapplicable",
                    "type": [
                        "boolean",
                        "null"
                    ],
                    "description": "Whether the matrix part is an isometry of the setting's metric, i.e. it preserves every metric tensor of the setting's crystal family expressed in this basis.\nFor a same-setting matrix `M` and metric tensor `g`, the criterion is `M^T g M = g` for every positive-definite metric in that family.\nThis is orthogonality with respect to the actual (generally non-Cartesian) lattice metric, not orthogonality of the matrix as a plain array: hexagonal sixfold rotations are isometries, whereas a cell-enlarging transform is not."
                }
            },
            "examples": [
                {
                    "matrix": [
                        [
                            "-1",
                            "0",
                            "0"
                        ],
                        [
                            "0",
                            "-1",
                            "0"
                        ],
                        [
                            "0",
                            "0",
                            "1"
                        ]
                    ],
                    "vector": [
                        "0",
                        "0",
                        "0"
                    ],
                    "xyz": "-x,-y,z",
                    "det": 1,
                    "is_orthogonal": true
                }
            ]
        }
    },
    "examples": [
        {
            "hall_entry": "p_1",
            "it_number": 1,
            "to_hall_entry": "p_1",
            "index": 1,
            "affine_transformation": {
                "matrix": [
                    [
                        "1",
                        "0",
                        "0"
                    ],
                    [
                        "0",
                        "1",
                        "0"
                    ],
                    [
                        "0",
                        "0",
                        "1"
                    ]
                ],
                "vector": [
                    "0",
                    "0",
                    "0"
                ]
            }
        }
    ]
}
Hall to IT standard transform (property)
