`visualdynamics.core.unit_choices`¶

unit_choices ¶

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

Objects are imported without units when their source does not declare them. The user sets the units in the imported-units pane (see MainWindow.show_units_panel), and these lists are what it offers.

The lists are grouped by dimension, so a channel the file calls an acceleration is offered the four acceleration units instead of every unit in the list. They are shortlists, not limits: every unit cell accepts any unit visualdynamics can read, typed or pasted.

Functions:

Name	Description
`shown_dimension`	The word for a dimension in the interface: 'length' is shown as
`stored_dimension`	The stored dimension tag for a word the interface shows; the
`base_dimension`	The quantity whose unit the user picks, given a record's dimension.
`units_for`	The units to offer for a dimension, or the fallback if it has no
`squared_per_hz`	The full unit of a PSD declared in `unit`: '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: 'length' is shown as 'displacement', 'modal_velocity' as 'modal velocity'.

Parameters:

Name	Type	Description	Default
`dimension`	`str`	The stored dimension tag.	required

Returns:

Type	Description
`str`	The word shown, or `dimension` itself if it has no other name.

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

def shown_dimension(dimension: str) -> str:
    """The word for a dimension in the interface: 'length' is shown as
    'displacement', 'modal_velocity' as 'modal velocity'.

    Parameters
    ----------
    dimension : str
        The stored dimension tag.

    Returns
    -------
    str
        The word shown, or `dimension` itself if it has no other name.
    """
    return DISPLAY_DIMENSIONS.get(dimension, dimension)

stored_dimension ¶

stored_dimension(shown: str) -> str

The stored dimension tag for a word the interface shows; the inverse of shown_dimension, ignoring case and surrounding spaces.

Parameters:

Name	Type	Description	Default
`shown`	`str`	The word, such as 'displacement'.	required

Returns:

Type	Description
`str`	The dimension tag, such as 'length'.

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

def stored_dimension(shown: str) -> str:
    """The stored dimension tag for a word the interface shows; the
    inverse of `shown_dimension`, ignoring case and surrounding spaces.

    Parameters
    ----------
    shown : str
        The word, such as 'displacement'.

    Returns
    -------
    str
        The dimension tag, such as 'length'.
    """
    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.

This is the leading term of the expression: an FRF's ordinate is declared by its numerator, and a PSD by the engineering unit whose square it stores.

Parameters:

Name	Type	Description	Default
`dimension`	`str`	A dimension tag or expression, such as 'acceleration/force'.	required

Returns:

Type	Description
`str`	The leading tag, such as 'acceleration'.

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.

    This is the leading term of the expression: an FRF's ordinate is
    declared by its numerator, and a PSD by the engineering unit whose
    square it stores.

    Parameters
    ----------
    dimension : str
        A dimension tag or expression, such as 'acceleration/force'.

    Returns
    -------
    str
        The leading tag, such as 'acceleration'.
    """
    return dimension.split('/')[0].split('*')[0]

units_for ¶

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

The units to offer for a dimension, or the fallback if it has no shortlist.

A file often names a quantity without giving its unit; a UNV with no dataset 164 says 'acceleration' and nothing more. The list is then limited to the units of that quantity.

Parameters:

Name	Type	Description	Default
`dimension`	`str or None`	A dimension tag or expression; only its leading term is used (`base_dimension`).	required
`fallback`	`sequence of str`	What to offer when the dimension has no shortlist. The default is every unit in every shortlist.	`None`

Returns:

Type	Description
`sequence of str`	The units, the most likely first.

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

def units_for(dimension: str | None,
              fallback: Sequence[str] | None = None) -> Sequence[str]:
    """The units to offer for a dimension, or the fallback if it has no
    shortlist.

    A file often names a quantity without giving its unit; a UNV with no
    dataset 164 says 'acceleration' and nothing more. The list is then
    limited to the units of that quantity.

    Parameters
    ----------
    dimension : str or None
        A dimension tag or expression; only its leading term is used
        (`base_dimension`).
    fallback : sequence of str, optional
        What to offer when the dimension has no shortlist. The default
        is every unit in every shortlist.

    Returns
    -------
    sequence of str
        The units, the most likely first.
    """
    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

The full unit of a PSD declared in unit: 'g' -> 'g²/Hz'.

A compound unit is bracketed, '(m/s²)²/Hz', so the square cannot be read as applying to the seconds only.

Parameters:

Name	Type	Description	Default
`unit`	`str or None`	The engineering unit the PSD was declared in.	required

Returns:

Type	Description
`str`	The label, or an empty string if `unit` is empty or None.

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

def squared_per_hz(unit: str | None) -> str:
    """The full unit of a PSD declared in `unit`: 'g' -> 'g²/Hz'.

    A compound unit is bracketed, '(m/s²)²/Hz', so the square cannot be
    read as applying to the seconds only.

    Parameters
    ----------
    unit : str or None
        The engineering unit the PSD was declared in.

    Returns
    -------
    str
        The label, or an empty string if `unit` is empty or None.
    """
    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.

'g' and 'g²/Hz' both give 'g'. The interface adds the suffix for clarity, and the user does not have to type it.

Parameters:

Name	Type	Description	Default
`text`	`str`	The label as shown or typed.	required

Returns:

Type	Description
`str`	The engineering unit in pint's spelling.

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`.

    'g' and 'g²/Hz' both give 'g'. The interface adds the suffix for
    clarity, and the user does not have to type it.

    Parameters
    ----------
    text : str
        The label as shown or typed.

    Returns
    -------
    str
        The engineering unit in pint's spelling.
    """
    text = _SQUARED_PER_HZ.sub('', text.strip())
    if text.startswith('(') and text.endswith(')'):
        text = text[1:-1]
    return plain_unit(text).strip()

visualdynamics.core.unit_choices¶

unit_choices ¶

Functions:¶

shown_dimension ¶

stored_dimension ¶

base_dimension ¶

units_for ¶

squared_per_hz ¶

engineering_unit ¶

`visualdynamics.core.unit_choices`¶