visualdynamics.core.unit_choices

unit_choices

Which units the interface offers, grouped by the quantity they measure.

Objects import unit-less when their source does not declare units. The user says what the values are in the imported-units pane (see MainWindow.show_units_panel); these lists are what it offers.

Grouping matters: a channel a file called an acceleration is offered four units rather than twenty-one, and the four are the only ones that could be right. The lists are shortlists, never limits — every unit cell takes anything visualdynamics can parse, typed or pasted.

In core rather than beside the widgets that offer these lists: which units an acceleration could be in is a fact about accelerations, and ChannelTable needs it to narrow a channel's unit column. It lived in gui/ and core reached up into it, which is the one direction imports must not go.

Functions:

Name	Description
shown_dimension	The word for a dimension in the interface.
stored_dimension	The dimension behind a word the interface offered.
base_dimension	The quantity whose unit the user picks, given a record's dimension.
units_for	The units worth offering for a dimension, everything if it is unknown.
squared_per_hz	How a PSD's declared unit actually reads: 'g' -> 'g²/Hz'.
engineering_unit	The unit inside a PSD label; the inverse of squared_per_hz.

Functions:

shown_dimension

shown_dimension(dimension: str) -> str

The word for a dimension in the interface.

Source code in src/visualdynamics/core/unit_choices.py

def shown_dimension(dimension: str) -> str:
    """The word for a dimension in the interface."""
    return DISPLAY_DIMENSIONS.get(dimension, dimension)

stored_dimension

stored_dimension(shown: str) -> str

The dimension behind a word the interface offered.

Source code in src/visualdynamics/core/unit_choices.py

def stored_dimension(shown: str) -> str:
    """The dimension behind a word the interface offered."""
    return _STORED.get(shown.strip().lower(), shown.strip().lower())

base_dimension

base_dimension(dimension: str) -> str

The quantity whose unit the user picks, given a record's dimension.

An FRF's ordinate is named by its numerator and a PSD is declared by the engineering unit whose square it stores, so in every case the choice is named by the leading term.

Source code in src/visualdynamics/core/unit_choices.py

def base_dimension(dimension: str) -> str:
    """The quantity whose unit the user picks, given a record's dimension.

    An FRF's ordinate is named by its numerator and a PSD is declared by the
    engineering unit whose square it stores, so in every case the choice is
    named by the leading term.
    """
    return dimension.split('/')[0].split('*')[0]

units_for

units_for(
    dimension: str | None,
    fallback: Sequence[str] | None = None,
) -> Sequence[str]

The units worth offering for a dimension, everything if it is unknown.

A file often names a quantity without sizing it — a UNV with no dataset 164 says 'acceleration' and stops. Narrowing the list to that quantity turns 21 choices into four, and the four are the only ones that could be right.

Source code in src/visualdynamics/core/unit_choices.py

def units_for(dimension: str | None,
              fallback: Sequence[str] | None = None) -> Sequence[str]:
    """The units worth offering for a dimension, everything if it is unknown.

    A file often names a quantity without sizing it — a UNV with no dataset
    164 says 'acceleration' and stops. Narrowing the list to that quantity
    turns 21 choices into four, and the four are the only ones that could be
    right.
    """
    if fallback is None:
        fallback = ALL_ORDINATE_UNITS
    return ORDINATE_UNITS.get(base_dimension(dimension or ''), fallback)

squared_per_hz

squared_per_hz(unit: str | None) -> str

How a PSD's declared unit actually reads: 'g' -> 'g²/Hz'.

A compound unit is bracketed, so '(m/s²)²/Hz' cannot be misread as m/s² squared only in the seconds.

Source code in src/visualdynamics/core/unit_choices.py

def squared_per_hz(unit: str | None) -> str:
    """How a PSD's declared unit actually reads: 'g' -> 'g²/Hz'.

    A compound unit is bracketed, so '(m/s²)²/Hz' cannot be misread as
    m/s² squared only in the seconds.
    """
    if not unit:
        return ''
    shown = pretty_unit(unit)
    return f'({shown})²/Hz' if is_compound_unit(unit) else f'{shown}²/Hz'

engineering_unit

engineering_unit(text: str) -> str

The unit inside a PSD label; the inverse of squared_per_hz.

Typing 'g' is accepted as readily as 'g²/Hz' — the suffix is what the interface adds for clarity, not something the user must reproduce.

Source code in src/visualdynamics/core/unit_choices.py

def engineering_unit(text: str) -> str:
    """The unit inside a PSD label; the inverse of `squared_per_hz`.

    Typing 'g' is accepted as readily as 'g²/Hz' — the suffix is what the
    interface adds for clarity, not something the user must reproduce.
    """
    text = _SQUARED_PER_HZ.sub('', text.strip())
    if text.startswith('(') and text.endswith(')'):
        text = text[1:-1]
    return plain_unit(text).strip()