Skip to content

qten.pointgroups.basis

Module reference for qten.pointgroups.basis.

basis

Point-group polynomial basis labels.

PointGroupBasis stores a homogeneous polynomial together with the representation metadata that identifies its symmetry sector. Abelian eigen-sectors usually carry a phase eigenvalue, while finite-group sectors carry a character-table irrep label.

PointGroupBasis dataclass 

PointGroupBasis(
    expr: Expr,
    axes: tuple[Symbol, ...],
    order: int,
    rep: ImmutableDenseMatrix,
    group: str = "generic",
    irrep: Expr | str | tuple[Expr, ...] = sy.Integer(1),
    irrep_dim: int = 1,
    copy_index: int = 0,
    component_index: int = 0,
)

Bases: Spatial

Polynomial basis label belonging to a point-group representation sector.

PointGroupBasis pairs an exact homogeneous polynomial expr with its coefficient vector rep in a fixed Euclidean monomial basis. Sector metadata distinguishes abelian phase labels from finite-group irrep labels.

Attributes:

Name Type Description
expr Expr

Exact polynomial expression reconstructed from rep.
axes tuple[Symbol, ...]

Ordered coordinate symbols used by the polynomial.
order int

Homogeneous degree of the polynomial.
rep ImmutableDenseMatrix

Coefficient vector in the Euclidean monomial basis of degree order, normalized so the first nonzero coefficient has unit magnitude.
group str

Group tag used in string labels. Defaults to "generic" for abelian eigen-bases and to a Hermann-Mauguin symbol for finite-group sectors.
irrep Expr | str | tuple[Expr, ...]

Sector label. Abelian eigen-bases store a phase eigenvalue; finite-group sectors store a character-table irrep name such as "A1" or "E".
irrep_dim int

Dimension of the irrep sector. Equals 1 for abelian phase labels.
copy_index int

Copy index when the same irrep appears with multiplicity.
component_index int

Component index within an irrep multiplet.
Notes

String rendering collapses to the bare polynomial when group == "generic" and the sector is the trivial abelian phase 1. Otherwise the label is formatted as group:irrep:expr.

expr instance-attribute 

expr: Expr

axes instance-attribute 

axes: tuple[Symbol, ...]

order instance-attribute 

order: int

rep instance-attribute 

rep: ImmutableDenseMatrix

group class-attribute instance-attribute 

group: str = 'generic'

irrep class-attribute instance-attribute 

irrep: Expr | str | tuple[Expr, ...] = sy.Integer(1)

irrep_dim class-attribute instance-attribute 

irrep_dim: int = 1

copy_index class-attribute instance-attribute 

copy_index: int = 0

component_index class-attribute instance-attribute 

component_index: int = 0

dim property 

dim: int

Number of coordinate axes for this basis label.

from_rep classmethod 

from_rep(
    rep: ImmutableDenseMatrix,
    euclidean_basis: ImmutableDenseMatrix,
    axes: tuple[Symbol, ...],
    order: int,
    *,
    group: str = "generic",
    irrep: Expr | str | tuple[Expr, ...] = sy.Integer(1),
    irrep_dim: int = 1,
    copy_index: int = 0,
    component_index: int = 0,
) -> PointGroupBasis

Build a normalized basis label from a Euclidean coefficient vector.

Parameters:

Name Type Description Default
rep ImmutableDenseMatrix

Coefficient vector in the Euclidean monomial basis.

 required
euclidean_basis ImmutableDenseMatrix

Row matrix of monomials matching rep.

 required
axes tuple[Symbol, ...]

Ordered coordinate symbols.

 required
order int

Homogeneous polynomial degree.

 required
group str

Group tag stored on the returned label.

 `"generic"`
irrep Expr | str | tuple[Expr, ...]

Sector label stored on the returned basis.

 Integer(1)
irrep_dim int

Dimension of the irrep sector.

 1
copy_index int

Copy index for repeated irreps.

 0
component_index int

Component index within an irrep multiplet.

 0

Returns:

Type Description
PointGroupBasis

Basis label whose rep is magnitude-normalized by the first nonzero coefficient while preserving overall sign.
Source code in src/qten/pointgroups/basis.py 
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
@classmethod
def from_rep(
    cls,
    rep: sy.ImmutableDenseMatrix,
    euclidean_basis: sy.ImmutableDenseMatrix,
    axes: tuple[sy.Symbol, ...],
    order: int,
    *,
    group: str = "generic",
    irrep: sy.Expr | str | tuple[sy.Expr, ...] = sy.Integer(1),
    irrep_dim: int = 1,
    copy_index: int = 0,
    component_index: int = 0,
) -> "PointGroupBasis":
    """
    Build a normalized basis label from a Euclidean coefficient vector.

    Parameters
    ----------
    rep : sy.ImmutableDenseMatrix
        Coefficient vector in the Euclidean monomial basis.
    euclidean_basis : sy.ImmutableDenseMatrix
        Row matrix of monomials matching `rep`.
    axes : tuple[sy.Symbol, ...]
        Ordered coordinate symbols.
    order : int
        Homogeneous polynomial degree.
    group : str, default `"generic"`
        Group tag stored on the returned label.
    irrep : sy.Expr | str | tuple[sy.Expr, ...], optional
        Sector label stored on the returned basis.
    irrep_dim : int, default 1
        Dimension of the irrep sector.
    copy_index : int, default 0
        Copy index for repeated irreps.
    component_index : int, default 0
        Component index within an irrep multiplet.

    Returns
    -------
    PointGroupBasis
        Basis label whose `rep` is magnitude-normalized by the first nonzero
        coefficient while preserving overall sign.
    """

    principle_term = next(x for x in rep if x != 0)
    normalized = sy.ImmutableDenseMatrix(sy.simplify(rep / sy.Abs(principle_term)))
    expr = sy.simplify(normalized.dot(euclidean_basis))
    return cls(
        expr=expr,
        axes=axes,
        order=order,
        rep=normalized,
        group=group,
        irrep=irrep,
        irrep_dim=irrep_dim,
        copy_index=copy_index,
        component_index=component_index,
    )

__str__ 

__str__() -> str
Source code in src/qten/pointgroups/basis.py 
137
138
139
140
141
142
143
144
145
146
147
148
def __str__(self) -> str:
    if sy.simplify(self.expr - 1) == 0:
        expr = "e"
    else:
        expr = str(self.expr)
    if (
        self.group == "generic"
        and isinstance(self.irrep, sy.Basic)
        and sy.simplify(self.irrep - 1) == 0
    ):
        return expr
    return f"{self.group}:{self.irrep}:{expr}"

__repr__ 

__repr__() -> str
Source code in src/qten/pointgroups/basis.py 
150
151
def __repr__(self) -> str:
    return self.__str__()

register_plot_method classmethod 

register_plot_method(name: str, backend: str = 'plotly')

Register a backend plotting function for this plottable class.

The returned decorator stores the function in the global plotting registry. Registered functions receive the object being plotted as their first argument, followed by any extra positional and keyword arguments supplied to plot().

Parameters:

Name Type Description Default
name str

User-facing plot method name, such as scatter, structure, or heatmap.

 required
backend str

Backend name that selects the implementation. The qten-plots extension currently uses plotly and matplotlib.

 'plotly'

Returns:

Type Description
Callable

Decorator that registers the provided plotting function and returns it unchanged.
Source code in src/qten/plottings/_plottings.py 
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
@classmethod
def register_plot_method(cls, name: str, backend: str = "plotly"):
    """
    Register a backend plotting function for this plottable class.

    The returned decorator stores the function in the global plotting
    registry. Registered functions receive the object being plotted as their
    first argument, followed by any extra positional and keyword arguments
    supplied to [`plot()`][qten.plottings.Plottable.plot].

    Parameters
    ----------
    name : str
        User-facing plot method name, such as `scatter`, `structure`, or
        `heatmap`.
    backend : str
        Backend name that selects the implementation. The `qten-plots`
        extension currently uses `plotly` and `matplotlib`.

    Returns
    -------
    Callable
        Decorator that registers the provided plotting function and returns
        it unchanged.
    """

    def decorator(func: Callable):
        # We register against 'cls' - the class this method was called on.
        Plottable._registry[(cls, name, backend)] = func
        return func

    return decorator

plot 

plot(method: str, backend: str = 'plotly', *args, **kwargs)

Dispatch a named plot method to a registered backend implementation.

The dispatcher first loads plotting entry points, then searches the instance type and its base classes for a matching (type, method, backend) registration. Additional arguments are forwarded unchanged to the selected backend function.

Parameters:

Name Type Description Default
method str

Plot method name registered for this object's type.

 required
backend str

Backend implementation to use. The qten-plots extension currently registers plotly and matplotlib.

 'plotly'
args

Positional arguments forwarded to the registered plotting function.

 ()
kwargs

Keyword arguments forwarded to the registered plotting function.

 {}

Returns:

Type Description
object

Backend-specific figure object returned by the registered plotting function, such as a Plotly or Matplotlib figure.

Raises:

Type Description
ValueError

If no plotting function is registered for the requested method and backend on this object.
See Also

qten_plots.plottables.PointCloud Public plottable helper object provided by the plotting extension.

Source code in src/qten/plottings/_plottings.py 
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
def plot(self, method: str, backend: str = "plotly", *args, **kwargs):
    """
    Dispatch a named plot method to a registered backend implementation.

    The dispatcher first loads plotting entry points, then searches the
    instance type and its base classes for a matching `(type, method,
    backend)` registration. Additional arguments are forwarded unchanged to
    the selected backend function.

    Parameters
    ----------
    method : str
        Plot method name registered for this object's type.
    backend : str
        Backend implementation to use. The `qten-plots` extension currently
        registers `plotly` and `matplotlib`.
    args
        Positional arguments forwarded to the registered plotting function.
    kwargs
        Keyword arguments forwarded to the registered plotting function.

    Returns
    -------
    object
        Backend-specific figure object returned by the registered plotting
        function, such as a Plotly or Matplotlib figure.

    Raises
    ------
    ValueError
        If no plotting function is registered for the requested method and
        backend on this object.

    See Also
    --------
    qten_plots.plottables.PointCloud
        Public plottable helper object provided by the plotting extension.
    """
    Plottable._ensure_backends_loaded()

    # Iterate over the MRO (Method Resolution Order) of the instance
    for class_in_hierarchy in type(self).__mro__:
        key = (class_in_hierarchy, method, backend)

        # Check the central registry
        if key in Plottable._registry:
            plot_func = Plottable._registry[key]
            return plot_func(self, *args, **kwargs)

    # If we reach here, no method was found. Provide a helpful error.
    self._raise_method_not_found(method, backend)