tilupy.notations

Attributes

`LABEL_OPTIONS`	Dictionary of configuration options for label generation.
`NOTATIONS`	Dictionary containing predefined notations.

Functions

`get_notation`(→ Notation)	Retrieve or construct a Notation object for a given name.
`get_operator_unit`(→ Unit)	Determine the unit associated with an operator based on its name and axis.
`make_long_name`(→ str)	Construct a long name for a notation combined with an operator.
`add_operator`(→ Notation)	Combine a notation with an operator to create a new notation.
`get_label`(→ str)	Generate a formatted label for a notation.
`set_label_options`(**kwargs)	Update the global label options.
`readme_to_params`(→ dict)	Convert a README file into a dictionary of parameters.
`make_rheol_string_fmt`(→ str)	Generate a formatted string template for rheological parameters.
`make_rheol_string`(→ str \| list[str])	Generate formatted strings for rheological parameters.

Classes

`Notation`	Notation system for physical quantities, symbols, or variables.
`Unit`	Subclass of pandas.Series to represent physical units and their exponents.
`LongName`	Generic container class to dynamically store LongName attributes as key-value pairs.
`Gender`	Generic container class to dynamically store Gender attributes as key-value pairs.

Module Contents

Attributes

tilupy.notations.LABEL_OPTIONS

Dictionary of configuration options for label generation.

This dictionary specifies the settings used for generating or formatting labels. It includes the language of the labels and the type of label representation.

Keys:

languagestr
Language used for the labels (e.g., “english”).
label_typestr
Type of label representation (e.g., “symbol” for symbolic labels).

tilupy.notations.NOTATIONS

Dictionary containing predefined notations.

Pre-made notations:

x [m]

y [m]

d [m]

z [m]

t [s]

xy [m2]

h [m]

hvert [m]

u [m1.s-1]

hu [m2.s-1]

ek [J]

Also some operators:

max

int

Functions

tilupy.notations.get_notation(name: str, language: str = None) → Notation

Retrieve or construct a Notation object for a given name.

This function attempts to fetch a predefined notation from the global tilupy.notations.NOTATIONS dictionary. If the notation is not found, it constructs a new tilupy.notations.Notation object based on the provided name. For composite names (e.g., “state_operator”), it recursively resolves the state and operator, then combines them using tilupy.notations.add_operator().

Parameters:

name (str) – The name of the notation to retrieve or construct. Can be a simple name (e.g., “velocity”) or a composite name (e.g., “velocity_int_t”).
language (str, optional) – The language to use for the long name of the notation. If not provided, the default language from LABEL_OPTIONS is used.

Returns:

The retrieved or constructed tilupy.notations.Notation object.

Return type:

tilupy.notations.Notation

tilupy.notations.get_operator_unit(name: str, axis: str) → Unit

Determine the unit associated with an operator based on its name and axis.

This function returns a tilupy.notations.Unit object corresponding to the operator’s name and the axis it operates on. For example, an integral operator (“int”) has different units depending on whether it integrates over time (“t”) or space (“x”, “y”, “xy”).

Parameters:

name (str) – The name of the operator (e.g., “int”).
axis (str or None) – The axis over which the operator acts (e.g., “t”, “x”, “y”, “xy”). If None, the default axis is used (e.g., “t” for “int”).

Returns:

The unit associated with the operator and axis.

Return type:

tilupy.notations.Unit

tilupy.notations.make_long_name(notation: Notation, operator: Notation, language: str = None) → str

Construct a long name for a notation combined with an operator.

This function generates a readable long name by combining the long names of a notation and an operator. It can be written in French or English.

Parameters:

notation (tilupy.notations.Notation) – The base notation object.
operator (tilupy.notations.Notation) – The operator notation object.
language (str, optional) – The language to use for the long name. If not provided, the default language from tilupy.notations.LABEL_OPTIONS is used. By default None.

Returns:

The combined long name in the specified language.

Return type:

str

tilupy.notations.add_operator(notation: Notation | str, operator: Notation | str, axis: str = None, language: str = None) → Notation

Combine a notation with an operator to create a new notation.

This function constructs a new tilupy.notations.Notation object by combining a base notation with an operator. It handles the symbol, unit, and long name of the resulting notation, taking into account the operator’s axis (if any).

Parameters:

notation (tilupy.notations.Notation or str) – The base notation object or its name.
operator (tilupy.notations.Notation or str) – The operator notation object or its name.
axis (str, optional) – The axis over which the operator acts (e.g., “t”, “x”, “y”). By default None.
language (str, optional) – The language to use for the long name. If not provided, the default language from tilupy.notations.LABEL_OPTIONS is used. By default None.

Returns:

The new Notation object resulting from the combination of the base notation and the operator.

Return type:

tilupy.notations.Notation

tilupy.notations.get_label(notation: Notation, with_unit: bool = True, label_type: str = None, language: str = None) → str

Generate a formatted label for a notation.

This function creates a label for a notation, either in literal form (long name) or symbolic form (symbol). It can optionally include the unit in the label.

Parameters:

notation (tilupy.notations.Notation or str) – The notation object or its name.
with_unit (bool, optional) – If True, the unit is included in the label. By default True.
label_type (str, optional) – The type of label to generate: “litteral” (long name) or “symbol” (symbol). If not provided, the default label type from tilupy.notations.LABEL_OPTIONS is used. By default None.
language (str, optional) – The language to use for the label. If not provided, the default language from tilupy.notations.LABEL_OPTIONS is used. By default None.

Returns:

The formatted label for the notation, optionally including the unit.

Return type:

str

tilupy.notations.set_label_options(**kwargs)

Update the global label options.

This function updates the global tilupy.notations.LABEL_OPTIONS dictionary with the provided keyword arguments. It allows dynamic configuration of label generation settings, such as language and label type.

Parameters:: **kwargs (dict) – Key-value pairs to update in tilupy.notations.LABEL_OPTIONS. Valid keys include “language” and “label_type”.

tilupy.notations.readme_to_params(file: str, readme_param_match: dict = None) → dict

Convert a README file into a dictionary of parameters.

This function reads a README file and extracts key-value pairs, optionally using a mapping dictionary to rename the keys. Each line in the file is expected to contain a key and a value separated by whitespace.

Parameters:

file (str) – Path to the README file to read.
readme_param_match (dict, optional) – A dictionary mapping keys in the README file to new keys in the output dictionary. If not provided, the keys are used as-is. By default None.

Returns:

A dictionary of parameters extracted from the README file.

Return type:

dict

tilupy.notations.make_rheol_string_fmt(rheoldict: dict) → str

Generate a formatted string template for rheological parameters.

This function constructs a string template for rheological parameters based on the provided dictionary and rheological law. The template includes placeholders for parameter values, which can later be formatted with specific values.

Parameters:: rheoldict (dict) – A dictionary of rheological parameters (e.g., “delta1”, “ksi”).
Returns:: A formatted string template for the rheological parameters.
Return type:: str

tilupy.notations.make_rheol_string(rheoldict: dict, law: str) → str | list[str]

Generate formatted strings for rheological parameters.

This function creates formatted strings for rheological parameters based on the provided dictionary and rheological law. It handles multiple parameter sets (e.g., for different time steps or conditions) and formats each set according to the specified law.

Parameters:

rheoldict (dict) – A dictionary of rheological parameters. Values can be lists of parameters for multiple sets.
law (str) – The rheological law to use. Can be “coulomb”, “voellmy” or “pouliquen_2002”.

Returns:

The formatted string(s) for the rheological parameters. If there is only one parameter set, a single string is returned. Otherwise, a list of strings is returned.

Return type:

str or list[str]

Classes

class tilupy.notations.Notation(name: str, long_name: LongName | str = None, gender: Gender | str = None, symbol: str = None, unit: Unit = None)

Notation system for physical quantities, symbols, or variables.

This class allows the definition of a notation with a name, long name, gender, symbol, and unit. It provides properties to access and modify these attributes, and a method to retrieve the long name in a specific language.

Parameters:

name (str) – The short name or identifier of the notation.
long_name (tilupy.notations.LongName or str, optional) – The long name of the notation. If a dictionary is provided, it is converted to a tilupy.notations.LongName object. By default None.
gender (tilupy.notations.Gender, optional) – The gender associated with the notation. If a dictionary is provided, it is converted to a tilupy.notations.Gender object. By default None.
symbol (str, optional) – The symbol representing the notation. By default None.
unit (tilupy.notations.Unit, optional) – The unit associated with the notation. By default None.

_name

The short name or identifier of the notation.

Type:: str

_long_name

The long name of the notation, which can be language-specific or gender-specific.

Type:: tilupy.notations.LongName or str

_gender

The gender associated with the notation, if applicable.

Type:: tilupy.notations.Gender

_symbol

The symbol representing the notation (e.g., mathematical symbol).

Type:: str

_unit

The unit associated with the notation (e.g., physical unit).

Type:: tilupy.notations.Unit

property name

Get name.

Returns:: Attribute _name
Return type:: str

property unit

Get unit.

Returns:: Attribute _unit
Return type:: tilupy.notations.Unit

property gender

Get gender.

Returns:: Attribute _gender
Return type:: tilupy.notations.Gender

property symbol

Get symbol.

Returns:: Attribute _symbol
Return type:: str

property long_name

Get long name.

Returns:: Attribute _long_name
Return type:: tilupy.notations.LongName

get_long_name(language: str = None, gender: str = None) → str

Retrieve the long name of the notation in the specified language and gender form.

The method retrieves the long name in the specified language (defaulting to the language in tilupy.notations.LABEL_OPTIONS). If a gender is provided, the method returns the gender-specific form of the long name.

Parameters:

language (str, optional) – The language in which to retrieve the long name. If not provided, the language from tilupy.notations.LABEL_OPTIONS is used.
gender (str, optional) – The gender form of the long name to retrieve. If not provided, the default form is returned.

Returns:

The long name in the specified language and gender form. If the long name is a string, it is returned as-is.

Return type:

str

class tilupy.notations.Unit(series: pandas.Series = None, **kwargs)

Bases: pandas.Series

Subclass of pandas.Series to represent physical units and their exponents.

This class allows the creation of unit objects as combinations of base units (e.g., “Pa”, “N”, “kg”) with their respective exponents. It supports basic operations like multiplication and provides a method to generate a LaTeX-formatted label for the unit combination.

Parameters:

series (pandas.Series, optional) – An existing Series to initialize the Unit object.
**kwargs (dict) – Key-value pairs where keys are unit names (from Unit.UNITS) and values are their exponents (as integers or floats). If provided, only units in Unit.UNITS are allowed.

Raises:

ValueError – If a key in kwargs is not in Unit.UNITS.

UNITS = ['Pa', 'N', 'kg', 'm', 's', 'J']: List of available units.

__mul__(other)

Multiply two Unit objects.

The multiplication combines the exponents of matching units. Units with zero exponents are dropped from the result.

Parameters:: other (tilupy.notations.Unit) – Another tilupy.notations.Unit object to multiply with.
Returns:: A new Unit object representing the product of the two units.
Return type:: tilupy.notations.Unit

get_label()

Generate a LaTeX-formatted string representation of the unit.

The label combines positive and negative exponents, omitting exponents of 1. Positive exponents are written as superscripts, while negative exponents are enclosed in curly braces (for LaTeX compatibility).

Returns:: A LaTeX-formatted string representing the unit (e.g., “kg m s$^{-2}$”). Returns an empty string if the Unit object is empty.
Return type:: str

class tilupy.notations.LongName(**kwargs)

Bases: object

Generic container class to dynamically store LongName attributes as key-value pairs.

This class allows the creation of objects with arbitrary attributes, which are passed as keyword arguments during initialization.

Parameters:: **kwargs (dict) – Arbitrary keyword arguments. Each key-value pair is added as an attribute to the object.

class tilupy.notations.Gender(**kwargs)

Bases: object

Generic container class to dynamically store Gender attributes as key-value pairs.

This class allows the creation of objects with arbitrary attributes, which are passed as keyword arguments during initialization.

Parameters:: **kwargs (dict) – Arbitrary keyword arguments. Each key-value pair is added as an attribute to the object.