tilupy.notations ================ .. py:module:: tilupy.notations Attributes ---------- .. autoapisummary:: tilupy.notations.LABEL_OPTIONS tilupy.notations.NOTATIONS Functions --------- .. autoapisummary:: tilupy.notations.get_notation tilupy.notations.get_operator_unit tilupy.notations.make_long_name tilupy.notations.add_operator tilupy.notations.get_label tilupy.notations.set_label_options tilupy.notations.readme_to_params tilupy.notations.make_rheol_string_fmt tilupy.notations.make_rheol_string Classes ------- .. autoapisummary:: tilupy.notations.Notation tilupy.notations.Unit tilupy.notations.LongName tilupy.notations.Gender Module Contents --------------- Attributes ^^^^^^^^^^ .. py:data:: 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: - language : str Language used for the labels (e.g., "english"). - label_type : str Type of label representation (e.g., "symbol" for symbolic labels). .. py:data:: 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 ^^^^^^^^^ .. py:function:: 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 :data:`tilupy.notations.NOTATIONS` dictionary. If the notation is not found, it constructs a new :class:`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 :func:`tilupy.notations.add_operator`. :param name: 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"). :type name: str :param language: The language to use for the long name of the notation. If not provided, the default language from `LABEL_OPTIONS` is used. :type language: str, optional :returns: The retrieved or constructed :class:`tilupy.notations.Notation` object. :rtype: tilupy.notations.Notation .. py:function:: 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 :class:`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"). :param name: The name of the operator (e.g., "int"). :type name: str :param axis: 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"). :type axis: str or None :returns: The unit associated with the operator and axis. :rtype: tilupy.notations.Unit .. py:function:: 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. :param notation: The base notation object. :type notation: tilupy.notations.Notation :param operator: The operator notation object. :type operator: tilupy.notations.Notation :param language: The language to use for the long name. If not provided, the default language from :data:`tilupy.notations.LABEL_OPTIONS` is used. By default None. :type language: str, optional :returns: The combined long name in the specified language. :rtype: str .. py:function:: 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 :class:`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). :param notation: The base notation object or its name. :type notation: tilupy.notations.Notation or str :param operator: The operator notation object or its name. :type operator: tilupy.notations.Notation or str :param axis: The axis over which the operator acts (e.g., "t", "x", "y"). By default None. :type axis: str, optional :param language: The language to use for the long name. If not provided, the default language from :data:`tilupy.notations.LABEL_OPTIONS` is used. By default None. :type language: str, optional :returns: The new Notation object resulting from the combination of the base notation and the operator. :rtype: tilupy.notations.Notation .. py:function:: 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. :param notation: The notation object or its name. :type notation: tilupy.notations.Notation or str :param with_unit: If True, the unit is included in the label. By default True. :type with_unit: bool, optional :param label_type: The type of label to generate: "litteral" (long name) or "symbol" (symbol). If not provided, the default label type from :data:`tilupy.notations.LABEL_OPTIONS` is used. By default None. :type label_type: str, optional :param language: The language to use for the label. If not provided, the default language from :data:`tilupy.notations.LABEL_OPTIONS` is used. By default None. :type language: str, optional :returns: The formatted label for the notation, optionally including the unit. :rtype: str .. py:function:: set_label_options(**kwargs) Update the global label options. This function updates the global :data:`tilupy.notations.LABEL_OPTIONS` dictionary with the provided keyword arguments. It allows dynamic configuration of label generation settings, such as language and label type. :param \*\*kwargs: Key-value pairs to update in :data:`tilupy.notations.LABEL_OPTIONS`. Valid keys include "language" and "label_type". :type \*\*kwargs: dict .. py:function:: 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. :param file: Path to the README file to read. :type file: str :param readme_param_match: 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. :type readme_param_match: dict, optional :returns: A dictionary of parameters extracted from the README file. :rtype: dict .. py:function:: 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. :param rheoldict: A dictionary of rheological parameters (e.g., "delta1", "ksi"). :type rheoldict: dict :returns: A formatted string template for the rheological parameters. :rtype: str .. py:function:: 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. :param rheoldict: A dictionary of rheological parameters. Values can be lists of parameters for multiple sets. :type rheoldict: dict :param law: The rheological law to use. Can be "coulomb", "voellmy" or "pouliquen_2002". :type law: str :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. :rtype: str or list[str] Classes ^^^^^^^ .. py:class:: 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. :param name: The short name or identifier of the notation. :type name: str :param long_name: The long name of the notation. If a dictionary is provided, it is converted to a :any:`tilupy.notations.LongName` object. By default None. :type long_name: tilupy.notations.LongName or str, optional :param gender: The gender associated with the notation. If a dictionary is provided, it is converted to a :obj:`tilupy.notations.Gender` object. By default None. :type gender: tilupy.notations.Gender, optional :param symbol: The symbol representing the notation. By default None. :type symbol: str, optional :param unit: The unit associated with the notation. By default None. :type unit: tilupy.notations.Unit, optional .. attribute:: _name The short name or identifier of the notation. :type: str .. attribute:: _long_name The long name of the notation, which can be language-specific or gender-specific. :type: tilupy.notations.LongName or str .. attribute:: _gender The gender associated with the notation, if applicable. :type: tilupy.notations.Gender .. attribute:: _symbol The symbol representing the notation (e.g., mathematical symbol). :type: str .. attribute:: _unit The unit associated with the notation (e.g., physical unit). :type: tilupy.notations.Unit .. py:property:: name Get name. :returns: Attribute :attr:`_name` :rtype: str .. py:property:: unit Get unit. :returns: Attribute :attr:`_unit` :rtype: tilupy.notations.Unit .. py:property:: gender Get gender. :returns: Attribute :attr:`_gender` :rtype: tilupy.notations.Gender .. py:property:: symbol Get symbol. :returns: Attribute :attr:`_symbol` :rtype: str .. py:property:: long_name Get long name. :returns: Attribute :attr:`_long_name` :rtype: tilupy.notations.LongName .. py:method:: 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 :data:`tilupy.notations.LABEL_OPTIONS`). If a gender is provided, the method returns the gender-specific form of the long name. :param language: The language in which to retrieve the long name. If not provided, the language from :data:`tilupy.notations.LABEL_OPTIONS` is used. :type language: str, optional :param gender: The gender form of the long name to retrieve. If not provided, the default form is returned. :type gender: str, optional :returns: The long name in the specified language and gender form. If the long name is a string, it is returned as-is. :rtype: str .. py:class:: Unit(series: pandas.Series = None, **kwargs) Bases: :py:obj:`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. :param series: An existing Series to initialize the Unit object. :type series: pandas.Series, optional :param \*\*kwargs: 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. :type \*\*kwargs: dict :raises ValueError: If a key in `kwargs` is not in `Unit.UNITS`. .. py:attribute:: UNITS :value: ['Pa', 'N', 'kg', 'm', 's', 'J'] List of available units. .. py:method:: __mul__(other) Multiply two Unit objects. The multiplication combines the exponents of matching units. Units with zero exponents are dropped from the result. :param other: Another :class:`tilupy.notations.Unit` object to multiply with. :type other: tilupy.notations.Unit :returns: A new Unit object representing the product of the two units. :rtype: tilupy.notations.Unit .. py:method:: 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. :rtype: str .. py:class:: LongName(**kwargs) Bases: :py:obj:`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. :param \*\*kwargs: Arbitrary keyword arguments. Each key-value pair is added as an attribute to the object. :type \*\*kwargs: dict .. py:class:: Gender(**kwargs) Bases: :py:obj:`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. :param \*\*kwargs: Arbitrary keyword arguments. Each key-value pair is added as an attribute to the object. :type \*\*kwargs: dict