ansys-units 0.5.dev0__tar.gz → 0.6.dev0__tar.gz

{ansys_units-0.5.dev0 → ansys_units-0.6.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ansys-units
-Version: 0.5.dev0
+Version: 0.6.dev0
 Summary: Pythonic interface for units, unit systems, and unit conversions.
 Author-email: "ANSYS, Inc." <pyansys.core@ansys.com>
 Maintainer-email: "ANSYS, Inc." <pyansys.core@ansys.com>
@@ -19,7 +19,7 @@ Requires-Dist: importlib-metadata>=4.0
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: ansys-sphinx-theme==1.3.2 ; extra == "doc"
 Requires-Dist: pdf2image==1.17.0 ; extra == "doc"
-Requires-Dist: quarto-cli==1.6.42 ; extra == "doc"
+Requires-Dist: quarto-cli==1.7.29 ; extra == "doc"
 Requires-Dist: matplotlib==3.10.1 ; extra == "doc"
 Requires-Dist: numpydoc==1.8.0 ; extra == "doc"
 Requires-Dist: Sphinx==7.4.7 ; extra == "doc"
@@ -27,8 +27,8 @@ Requires-Dist: sphinx-copybutton==0.5.2 ; extra == "doc"
 Requires-Dist: sphinx-gallery==0.19.0 ; extra == "doc"
 Requires-Dist: sphinx-toggleprompt==0.6.0 ; extra == "doc"
 Requires-Dist: numpy==2.2.3 ; extra == "lists"
-Requires-Dist: pytest==8.3.4 ; extra == "tests"
-Requires-Dist: pytest-cov==6.0.0 ; extra == "tests"
+Requires-Dist: pytest==8.3.5 ; extra == "tests"
+Requires-Dist: pytest-cov==6.1.1 ; extra == "tests"
 Requires-Dist: pytest-mock==3.14.0 ; extra == "tests"
 Requires-Dist: pint==0.24.4 ; extra == "tests"
 Project-URL: Documentation, https://ansunits.docs.pyansys.com

{ansys_units-0.5.dev0 → ansys_units-0.6.dev0}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "flit_core.buildapi"
 [project]
 # Check https://flit.readthedocs.io/en/latest/pyproject_toml.html for all available sections
 name = "ansys-units"
-version = "0.5.dev0"
+version = "0.6.dev0"
 description = "Pythonic interface for units, unit systems, and unit conversions."
 readme = "README.rst"
 requires-python = ">=3.9,<4"
@@ -32,7 +32,7 @@ dependencies = [
 doc = [
     "ansys-sphinx-theme==1.3.2",
     "pdf2image==1.17.0",
-    "quarto-cli==1.6.42",
+    "quarto-cli==1.7.29",
     "matplotlib==3.10.1",
     "numpydoc==1.8.0",
     "Sphinx==7.4.7",
@@ -41,8 +41,8 @@ doc = [
     "sphinx-toggleprompt==0.6.0",
 ]
 tests = [
-    "pytest==8.3.4",
-    "pytest-cov==6.0.0",
+    "pytest==8.3.5",
+    "pytest-cov==6.1.1",
     "pytest-mock==3.14.0",
     "pint==0.24.4",
 ]

{ansys_units-0.5.dev0 → ansys_units-0.6.dev0}/src/ansys/units/__init__.py

@@ -30,20 +30,19 @@ __version__ = importlib_metadata.version(__name__.replace(".", "-"))
 
 import os
 
-from ansys.units._constants import (  # noqa: F401
-    _base_units,
-    _derived_units,
-    _multipliers,
-    _quantity_units_table,
-    _QuantityType,
-    _unit_systems,
+from ansys.units.base_dimensions import BaseDimensions
+from ansys.units.dimensions import Dimensions
+from ansys.units.quantity import Quantity, get_si_value
+from ansys.units.quantity_dimensions import QuantityDimensions
+from ansys.units.systems import UnitSystem
+from ansys.units.unit import Unit
+from ansys.units.unit_registry import UnitRegistry
+from ansys.units.variable_descriptor import (
+    ConversionStrategy,
+    MappingConversionStrategy,
+    VariableCatalog,
+    VariableDescriptor,
 )
-from ansys.units.base_dimensions import BaseDimensions  # noqa: F401
-from ansys.units.dimensions import Dimensions  # noqa: F401
-from ansys.units.quantity import Quantity, get_si_value  # noqa: F401
-from ansys.units.systems import UnitSystem  # noqa: F401
-from ansys.units.unit import Unit  # noqa: F401
-from ansys.units.unit_registry import UnitRegistry  # noqa: F401
 
 _THIS_DIRNAME = os.path.dirname(__file__)
 _README_FILE = os.path.normpath(os.path.join(_THIS_DIRNAME, "docs", "README.rst"))
@@ -51,3 +50,19 @@ _README_FILE = os.path.normpath(os.path.join(_THIS_DIRNAME, "docs", "README.rst"
 if os.path.exists(_README_FILE):
     with open(_README_FILE, encoding="utf8") as f:
         __doc__ = f.read()
+
+
+__all__ = [
+    "BaseDimensions",
+    "Dimensions",
+    "Quantity",
+    "get_si_value",
+    "UnitSystem",
+    "Unit",
+    "UnitRegistry",
+    "QuantityDimensions",
+    "VariableDescriptor",
+    "VariableCatalog",
+    "ConversionStrategy",
+    "MappingConversionStrategy",
+]

{ansys_units-0.5.dev0 → ansys_units-0.6.dev0}/src/ansys/units/dimensions.py

@@ -75,10 +75,7 @@ class Dimensions:
         str
             A string version of the dimensions.
         """
-        dims = {x.name: y for x, y in self}
-        if not dims:
-            dims = ""
-        return str(dims)
+        return str({x.name: y for x, y in self})
 
     def __str__(self):
         return self._to_string()

ansys_units-0.6.dev0/src/ansys/units/quantity_dimensions.py

@@ -0,0 +1,267 @@
+# Copyright (C) 2023 - 2025 ANSYS, Inc. and/or its affiliates.
+
+# SPDX-License-Identifier: MIT
+#
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""
+Defines immutable objects representing SI base and derived physical dimensions.
+
+This module provides globally defined `Dimensions` instances corresponding to the
+seven SI base quantities (e.g., mass, time) and many commonly used derived quantities
+(e.g., force, energy, pressure). These dimension definitions are used internally
+for dimensional analysis, quantity construction, and validation.
+
+Each dimension is represented as a `Dimensions` object, which captures the
+dimensional exponents of base quantities such as mass, length, and time.
+
+This module is not intended for direct modification at runtime. All objects
+are statically defined and immutable.
+
+Examples
+--------
+>>> from ansys.units.dimensions import Dimensions
+>>> from ansys.units.quantity_dimensions import QuantityDimensions
+
+>>> force = QuantityDimensions.FORCE
+>>> pressure = QuantityDimensions.PRESSURE
+>>> pressure == force / QuantityDimensions.AREA
+True
+"""
+
+from ansys.units.base_dimensions import BaseDimensions
+from ansys.units.dimensions import Dimensions
+
+# Local function to convert from a `BaseDimensions` enum object to a `Dimensions` object
+
+
+def _make_base_dimensions(dimension: BaseDimensions) -> Dimensions:
+    return Dimensions(dimensions={dimension: 1.0})
+
+
+def _expand_vector_quantities(cls):
+    angle = _make_base_dimensions(BaseDimensions.ANGLE)
+    for name in getattr(cls, "_vector_quantities", []):
+        value = getattr(cls, name)
+        # cartesian only added by default
+        setattr(cls, f"{name}_X", value)
+        setattr(cls, f"{name}_Y", value)
+        setattr(cls, f"{name}_Z", value)
+        # magnitude
+        setattr(cls, f"{name}_MAGNITUDE", value)
+    return cls
+
+
+@_expand_vector_quantities
+class QuantityDimensions:
+    """
+    Defines immutable dimension objects for standard physical quantities.
+
+    This class encapsulates SI base dimensions (e.g., MASS, TIME) and
+    commonly used derived dimensions (e.g., FORCE, PRESSURE, ENERGY),
+    using `Dimensions` instances.
+
+    These objects support arithmetic operations (multiplication, division,
+    exponentiation) to enable dimensional composition and analysis.
+
+    All attributes are class-level constants and should be treated as immutable.
+
+    Examples
+    --------
+    >>> QuantityDimensions.VELOCITY
+    Dimensions(dimensions={BaseDimensions.LENGTH: 1.0, BaseDimensions.TIME: -1.0})
+    """
+
+    # Dimensions of base quantities
+    MASS = _make_base_dimensions(BaseDimensions.MASS)
+    LENGTH = _make_base_dimensions(BaseDimensions.LENGTH)
+    TIME = _make_base_dimensions(BaseDimensions.TIME)
+    TEMPERATURE = _make_base_dimensions(BaseDimensions.TEMPERATURE)
+    CHEMICAL_AMOUNT = _make_base_dimensions(BaseDimensions.CHEMICAL_AMOUNT)
+    LIGHT = _make_base_dimensions(BaseDimensions.LIGHT)
+    CURRENT = _make_base_dimensions(BaseDimensions.CURRENT)
+
+    # Supplementary base quantities
+    ANGLE = _make_base_dimensions(BaseDimensions.ANGLE)
+    SOLID_ANGLE = _make_base_dimensions(BaseDimensions.SOLID_ANGLE)
+    TEMPERATURE_DIFFERENCE = _make_base_dimensions(
+        BaseDimensions.TEMPERATURE_DIFFERENCE
+    )
+
+    # Dimensions of derived quantities
+
+    # Kinematics and mechanics
+    AREA = LENGTH**2
+    VOLUME = LENGTH**3
+    FREQUENCY = TIME**-1
+    VELOCITY = LENGTH / TIME
+    ACCELERATION = VELOCITY / TIME
+    FORCE = MASS * ACCELERATION
+    PRESSURE = FORCE / AREA
+    STRESS = PRESSURE
+    JERK = LENGTH / TIME**3
+    SNAP = LENGTH / TIME**4
+    ANGULAR_VELOCITY = TIME**-1
+    ANGULAR_ACCELERATION = TIME**-2
+    VOLUMETRIC_FLOW = VOLUME / TIME
+    MOMENTUM = MASS * VELOCITY
+    ANGULAR_MOMENTUM = LENGTH**2 * MASS / TIME
+    TORQUE = LENGTH**2 * MASS / TIME**2
+    ENERGY = LENGTH**2 * MASS / TIME**2
+    POWER = ENERGY / TIME
+    DENSITY = MASS / VOLUME
+    SPECIFIC_VOLUME = VOLUME / MASS
+    ENERGY_DENSITY = ENERGY / VOLUME
+    SURFACE_TENSION = FORCE / LENGTH
+    KINEMATIC_VISCOSITY = AREA / TIME
+    DYNAMIC_VISCOSITY = PRESSURE * TIME
+    MASS_FLOW_RATE = MASS / TIME
+    MASS_CONTROL = MASS / TIME**3
+    FREQUENCY_DRIFT = TIME**-2
+    YANK = FORCE / TIME
+    WAVENUMBER = LENGTH**-1
+    AREA_DENSITY = MASS / AREA
+    ACTION = ENERGY * TIME
+    SPECIFIC_ENERGY = ENERGY / MASS
+    HEAT_FLUX_DENSITY = POWER / AREA
+    SURFACE_HEAT_FLUX = HEAT_FLUX_DENSITY
+    LINEAR_MASS_DENSITY = MASS / LENGTH
+    RADIANCE = POWER / (SOLID_ANGLE * AREA)
+    SPECTRAL_POWER = POWER / LENGTH
+    ABSORBED_DOSE_RATE = AREA / TIME**3
+    FUEL_EFFICIENCY = LENGTH**-2
+    SPECTRAL_IRRADIANCE = POWER / VOLUME
+    ENERGY_FLUX_DENSITY = POWER / AREA
+    COMPRESSIBILITY = PRESSURE**-1
+    RADIANT_EXPOSURE = ENERGY / AREA
+    MOMENT_OF_INERTIA = MASS * AREA
+    SPECIFIC_ANGULAR_MOMENTUM = ANGULAR_MOMENTUM / MASS
+    RADIANT_INTENSITY = POWER / SOLID_ANGLE
+    SPECTRAL_INTENSITY = POWER / (SOLID_ANGLE * LENGTH)
+    STRAIN_RATE = TIME**-1
+    AXIAL_VELOCITY = VELOCITY
+    RADIAL_VELOCITY = VELOCITY
+    TANGENTIAL_VELOCITY = VELOCITY
+
+    # Electromagnetics
+    ELECTRIC_CHARGE = TIME * CURRENT
+    ELECTRICAL_POTENTIAL = MASS * AREA * TIME**-3 / CURRENT
+    ELECTRICAL_CAPACITANCE = MASS**-1 * LENGTH**-2 * TIME**4 * CURRENT**2
+    ELECTRICAL_INDUCTANCE = MASS * LENGTH**2 * TIME**-2 * CURRENT**-2
+    ELECTRICAL_RESISTANCE = ELECTRICAL_POTENTIAL / CURRENT
+    ELECTRICAL_IMPEDANCE = ELECTRICAL_RESISTANCE
+    ELECTRICAL_REACTANCE = ELECTRICAL_RESISTANCE
+    ELECTRICAL_CONDUCTANCE = ELECTRICAL_RESISTANCE**-1
+    MAGNETIC_FLUX = MASS * LENGTH**2 * TIME**-2 * CURRENT**-1
+    MAGNETIC_INDUCTION = MASS * TIME**-2 * CURRENT**-1
+    MAGNETIC_PERMEABILITY = LENGTH * MASS * TIME**-2 * CURRENT**-2
+    MAGNETIC_VECTOR_POTENTIAL = LENGTH * MASS * TIME**-2 * CURRENT**-1
+
+    # Chemistry
+    MOLARITY = CHEMICAL_AMOUNT / VOLUME
+    MOLAR_VOLUME = VOLUME / CHEMICAL_AMOUNT
+    MOLAR_HEAT_CAPACITY = ENERGY / (TEMPERATURE * CHEMICAL_AMOUNT)
+    MOLAR_ENTROPY = MOLAR_HEAT_CAPACITY
+    MOLAR_ENERGY = ENERGY / CHEMICAL_AMOUNT
+    MOLALITY = CHEMICAL_AMOUNT / MASS
+    MOLAR_MASS = MASS / CHEMICAL_AMOUNT
+    CATALYTIC_EFFICIENCY = VOLUME / (CHEMICAL_AMOUNT * TIME)
+
+    # Photometry
+    LUMINOUS_FLUX = LIGHT * SOLID_ANGLE
+    ILLUMINANCE = LUMINOUS_FLUX / AREA
+    LUMINANCE = LIGHT / AREA
+    LUMINOUS_EXPOSURE = ILLUMINANCE * TIME
+
+    # Thermodynamics
+    HEAT_CAPACITY = ENERGY / TEMPERATURE
+    SPECIFIC_HEAT_CAPACITY = HEAT_CAPACITY / MASS
+    THERMAL_CONDUCTIVITY = POWER / (LENGTH * TEMPERATURE)
+    THERMAL_RESISTANCE = TEMPERATURE / POWER
+    TEMPERATURE_GRADIENT = TEMPERATURE / LENGTH
+    ENTHALPY = ENERGY
+    ENTROPY = ENERGY / TEMPERATURE
+    SPECIFIC_ENTHALPY = ENTHALPY / MASS
+    SPECIFIC_ENTROPY = ENTROPY / MASS
+    INTERNAL_ENERGY = ENERGY
+    TOTAL_ENERGY = ENERGY
+    SPECIFIC_TOTAL_ENERGY = TOTAL_ENERGY / MASS
+    SPECIFIC_INTERNAL_ENERGY = INTERNAL_ENERGY / MASS
+    TOTAL_TEMPERATURE = TEMPERATURE
+
+    # Turbulence
+    PRANDTL_NUMBER = Dimensions()
+    EFFECTIVE_PRANDTL_NUMBER = Dimensions()
+    EFFECTIVE_THERMAL_CONDUCTIVITY = THERMAL_CONDUCTIVITY
+    EFFECTIVE_VISCOSITY = DYNAMIC_VISCOSITY
+    PRODUCTION_OF_TURBULENT_KINETIC_ENERGY = MASS * LENGTH**-1 * TIME**-3
+    SPECIFIC_DISSIPATION_RATE = TIME**-1
+    TURBULENT_DISSIPATION_RATE = LENGTH**2 * TIME**3
+    TURBULENT_INTENSITY = Dimensions()
+    TURBULENT_VISCOSITY = DYNAMIC_VISCOSITY
+    TURBULENT_VISCOSITY_RATIO = Dimensions()
+    TURBULENT_REYNOLDS_NUMBER = Dimensions()
+    TURBULENT_KINETIC_ENERGY = LENGTH**2 * TIME**-2
+    WALL_Y_PLUS = Dimensions()
+    WALL_Y_STAR = Dimensions()
+
+    # Fluid pressure
+    STATIC_PRESSURE = PRESSURE  # equivalent
+    ABSOLUTE_PRESSURE = PRESSURE
+    DYNAMIC_PRESSURE = PRESSURE
+    TOTAL_PRESSURE = PRESSURE
+    PRESSURE_COEFFICIENT = Dimensions()
+
+    # Other fluid and related quantities
+    VORTICITY = TIME**-1
+    CONVECTIVE_COURANT_NUMBER = Dimensions()
+    CELL_REYNOLDS_NUMBER = Dimensions()
+    Q_CRITERION = TIME**-2
+    NORMALIZED_Q_CRITERION = Dimensions()
+    MESH_VELOCITY = VELOCITY
+    SPECIFIC_TOTAL_ENTHALPY = SPECIFIC_ENTHALPY
+    SURFACE_NUSSELT_NUMBER = Dimensions()
+    SURFACE_STANTON_NUMBER = Dimensions()
+    SKIN_FRICTION_COEFFICIENT = Dimensions()
+    SURFACE_HEAT_TRANSFER_COEFFICIENT = POWER * LENGTH**-2 * TEMPERATURE**-1
+    WALL_ADJACENT_HEAT_TRANSFER_COEFFICIENT = POWER * LENGTH**-2 * TEMPERATURE**-1
+    WALL_TEMPERATURE = TEMPERATURE
+    WALL_ADJACENT_TEMPERATURE = TEMPERATURE
+    WALL_TEMPERATURE_THIN = TEMPERATURE
+    WALL_SHEAR_STRESS = STRESS
+
+    # Coordinates
+    POSITION = LENGTH
+
+    # List of vector quantities. The only impact
+    # of not adding a vector quantity here is that
+    # the code will not autogenerate attributes
+    # <quantity>_X etc for that quantity.
+    _vector_quantities = [
+        "VELOCITY",
+        "ACCELERATION",
+        "VORTICITY",
+        "POSITION",
+        "MESH_VELOCITY",
+        "MOMENTUM",
+        "ANGULAR_MOMENTUM",
+        "TORQUE",
+        "FORCE",
+        "WALL_SHEAR_STRESS",
+    ]

{ansys_units-0.5.dev0 → ansys_units-0.6.dev0}/src/ansys/units/systems.py

@@ -23,7 +23,8 @@
 
 from __future__ import annotations
 
-from ansys.units import BaseDimensions, _base_units, _unit_systems
+from ansys.units import BaseDimensions
+from ansys.units._constants import _base_units, _unit_systems
 
 
 class UnitSystem:

{ansys_units-0.5.dev0 → ansys_units-0.6.dev0}/src/ansys/units/unit.py

@@ -28,6 +28,8 @@ from typing import Optional, Union
 from ansys.units import (
     BaseDimensions,
     Dimensions,
+)
+from ansys.units._constants import (
     _base_units,
     _derived_units,
     _multipliers,

ansys_units-0.6.dev0/src/ansys/units/variable_descriptor/__init__.py

@@ -0,0 +1,50 @@
+# Copyright (C) 2023 - 2025 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: MIT
+#
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""
+Package initialization for ansys.units.variable_descriptor.
+
+Exports the VariableCatalog catalog and core interfaces for working with
+physical quantities in a product-agnostic way.
+
+Example
+-------
+
+.. code-block:: python
+
+    from ansys.units.variable_descriptor import VariableCatalog
+    from ansys.fluent.core.variable_strategies import FluentSVarNamingStrategy
+
+    quantity = VariableCatalog.PRESSURE
+    strategy = FluentSVarNamingStrategy()
+
+    print(strategy.to_string(quantity))
+"""
+
+from .strategy import ConversionStrategy, MappingConversionStrategy
+from .variable_descriptor import VariableCatalog, VariableDescriptor
+
+__all__ = [
+    "VariableDescriptor",
+    "VariableCatalog",
+    "ConversionStrategy",
+    "MappingConversionStrategy",
+]

ansys_units-0.6.dev0/src/ansys/units/variable_descriptor/strategy.py

@@ -0,0 +1,240 @@
+# Copyright (C) 2023 - 2025 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: MIT
+#
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""
+Defines the ConversionStrategy base class for translating `VariableDescriptor` objects.
+
+Each concrete strategy maps `VariableDescriptor` instances to the string representations
+required by a specific system.
+"""
+
+from abc import ABC, abstractmethod
+import types
+
+from ansys.units.variable_descriptor.variable_descriptor import VariableDescriptor
+
+
+class ConversionStrategy(ABC):
+    """
+    Abstract base class for `VariableDescriptor` conversion strategies.
+
+    This class defines the interface for all conversion strategies. Derived classes
+    must implement the methods defined here to handle the conversion of `VariableDescriptor`
+    objects to and from their string representations, as well as to check if a
+    `VariableDescriptor` is supported.
+    """
+
+    @abstractmethod
+    def to_string(self, variable: VariableDescriptor | str | None) -> str | None:
+        """
+        Convert a `VariableDescriptor` to its string representation.
+
+        Parameters
+        ----------
+        variable : VariableDescriptor | str
+            The `VariableDescriptor` to convert, or a string representation.
+
+        Returns
+        -------
+        str
+            The string representation of the `VariableDescriptor`.
+
+        Raises
+        ------
+        NotImplementedError
+            If the method is not implemented in a derived class.
+        """
+        pass
+
+    @abstractmethod
+    def to_variable_descriptor(
+        self, variable: VariableDescriptor | str
+    ) -> VariableDescriptor:
+        """
+        Convert a string to its corresponding `VariableDescriptor`.
+
+        Parameters
+        ----------
+        variable : VariableDescriptor | str
+            The string representation to convert, or a `VariableDescriptor`.
+
+        Returns
+        -------
+        VariableDescriptor
+            The corresponding `VariableDescriptor` instance.
+
+        Raises
+        ------
+        NotImplementedError
+            If the method is not implemented in a derived class.
+        """
+        pass
+
+    @abstractmethod
+    def supports(self, variable: VariableDescriptor) -> bool:
+        """
+        Check if the given `VariableDescriptor` is supported by the strategy.
+
+        Parameters
+        ----------
+        variable : VariableDescriptor
+            The `VariableDescriptor` to check.
+
+        Returns
+        -------
+        bool
+            `True` if the `VariableDescriptor` is supported, `False` otherwise.
+
+        Raises
+        ------
+        NotImplementedError
+            If the method is not implemented in a derived class.
+        """
+        pass
+
+
+class MappingConversionStrategy(ConversionStrategy):
+    """
+    Intermediate base class for implementing VariableDescriptor conversion strategies.
+
+    This class simplifies the creation of concrete strategy classes by providing
+    default implementations for common methods. Classes inheriting from this base
+    class only need to define a `_mapping` dictionary that maps `VariableDescriptor`
+    instances to their corresponding string representations.
+
+    Attributes
+    ----------
+    _reverse_mapping : dict
+        A lazily initialized reverse mapping of `_mapping`, used for converting
+        strings back to `VariableDescriptor` instances.
+
+    Methods
+    -------
+    to_string(variable: VariableDescriptor | str) -> str
+        Converts a `VariableDescriptor` to its string representation. Raises a
+        `ValueError` if the variable is not supported.
+    to_variable_descriptor(variable: VariableDescriptor | str) -> VariableDescriptor
+        Converts a string to its corresponding `VariableDescriptor`.
+    supports(variable: VariableDescriptor) -> bool
+        Checks if the given `VariableDescriptor` is supported by the strategy.
+
+    Raises
+    ------
+    ValueError
+        If a `VariableDescriptor` is not supported during conversion to a string.
+    """
+
+    def __init__(self):
+        """
+        Initialize the MappingConversionStrategy.
+
+        This constructor initializes the reverse mapping attribute to `None`.
+        The reverse mapping is lazily initialized when accessed via the `_reverse_mapping` property.
+        """
+        self.__reverse_mapping = None
+
+    @property
+    def _reverse_mapping(self):
+        """
+        Get the reverse mapping of `_mapping`.
+
+        The reverse mapping is a dictionary that maps string representations
+        back to their corresponding `VariableDescriptor` instances. It is lazily
+        initialized on first access.
+
+        Returns
+        -------
+        dict
+            A dictionary mapping string representations to `VariableDescriptor` instances.
+        """
+        if self.__reverse_mapping is None:
+            self.__reverse_mapping = {x: y for y, x in self._mapping.items()}
+        return self.__reverse_mapping
+
+    def to_string(self, variable: VariableDescriptor | str | None) -> str | None:
+        """
+        Convert a `VariableDescriptor` to its string representation.
+
+        If the input is already a string, it is returned as-is. If the input
+        is a `VariableDescriptor` and is supported by the strategy, its string
+        representation is returned. Otherwise, a `ValueError` is raised.
+
+        Parameters
+        ----------
+        variable : VariableDescriptor | str
+            The `VariableDescriptor` to convert, or a string representation.
+
+        Returns
+        -------
+        str
+            The string representation of the `VariableDescriptor`.
+
+        Raises
+        ------
+        ValueError
+            If the `VariableDescriptor` is not supported by the strategy.
+        """
+        if isinstance(variable, (str, types.NoneType)):
+            return variable
+        if not self.supports(variable):
+            raise ValueError(f"{variable.name} not supported.")
+        return self._mapping[variable]
+
+    def to_variable_descriptor(
+        self, variable: VariableDescriptor | str
+    ) -> VariableDescriptor:
+        """
+        Convert a string to its corresponding `VariableDescriptor`.
+
+        If the input is already a `VariableDescriptor`, it is returned as-is.
+        Otherwise, the string is converted to a `VariableDescriptor` using the
+        reverse mapping.
+
+        Parameters
+        ----------
+        variable : VariableDescriptor | str
+            The string representation to convert, or a `VariableDescriptor`.
+
+        Returns
+        -------
+        VariableDescriptor
+            The corresponding `VariableDescriptor` instance, or `None` if the
+            string is not found in the reverse mapping.
+        """
+        if isinstance(variable, VariableDescriptor):
+            return variable
+        return self._reverse_mapping.get(variable)
+
+    def supports(self, variable: VariableDescriptor) -> bool:
+        """
+        Check if the given `VariableDescriptor` is supported by the strategy.
+
+        Parameters
+        ----------
+        variable : VariableDescriptor
+            The `VariableDescriptor` to check.
+
+        Returns
+        -------
+        bool
+            `True` if the `VariableDescriptor` is supported, `False` otherwise.
+        """
+        return variable in self._mapping

ansys_units-0.6.dev0/src/ansys/units/variable_descriptor/variable_descriptor.py

@@ -0,0 +1,270 @@
+# Copyright (C) 2023 - 2025 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: MIT
+#
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""
+Defines the core VariableDescriptor class and predefined quantities.
+
+This module provides a structured, extensible way to represent variables based on
+physical quantities (e.g., pressure, velocity) independently of any product-specific
+naming conventions.
+"""
+
+from dataclasses import dataclass
+
+from ansys.units.dimensions import Dimensions
+from ansys.units.quantity_dimensions import QuantityDimensions
+
+
+@dataclass(frozen=True)
+class VariableDescriptor:
+    """Defines a physical quantity variable descriptor."""
+
+    name: str
+    dimension: Dimensions
+
+    def __hash__(self):
+        return hash((self.name, str(self.dimension)))
+
+
+def _validate_and_transform_variable(variable: str) -> str:
+    """
+    Validate and transform a variable name.
+
+    Ensures the variable name is uppercase and returns its lowercase equivalent.
+
+    Parameters
+    ----------
+    variable : str
+        The name of the variable.
+
+    Returns
+    -------
+    str
+        The lowercase equivalent of the variable name.
+
+    Raises
+    ------
+    ValueError
+        If the variable name is not uppercase.
+    """
+    if not variable.isupper():
+        raise ValueError(
+            f"Variable names in VariableCatalog must be uppercase. "
+            f"Invalid name: '{variable}'."
+        )
+    return variable.lower()
+
+
+def _build_variable_descriptors_from_dimensions() -> dict[str, VariableDescriptor]:
+    """
+    Generate a dictionary of variable descriptors from QuantityDimensions.
+
+    This function iterates over all uppercase attributes in QuantityDimensions and
+    creates VariableDescriptor instances for each valid dimension.
+    """
+    catalog = {}
+    for attr_name in dir(QuantityDimensions):
+        dimension = getattr(QuantityDimensions, attr_name)
+        if isinstance(dimension, Dimensions):
+            catalog[attr_name] = VariableDescriptor(
+                name=_validate_and_transform_variable(attr_name), dimension=dimension
+            )
+    return catalog
+
+
+class VariableCatalog:
+    """A catalog of variable descriptors."""
+
+    # Load from generator
+    _generated = _build_variable_descriptors_from_dimensions()
+
+    # Inject generated descriptors as class attributes
+    for _key, _descriptor in _generated.items():
+        locals()[_key] = _descriptor
+
+    @classmethod
+    def all(cls) -> dict[str, list[VariableDescriptor]]:
+        """
+        Return all defined
+        :class:`~ansys.units.variable_descriptor.variable_descriptor.VariableDescriptor`
+        objects, organized by subcategory.
+
+        Returns
+        -------
+        dict[str, list[VariableDescriptor]]
+            A dictionary where keys are subcategory names (or "main" for the top-level catalog)
+            and values are lists of :class:`~ansys.units.variable_descriptor.variable_descriptor.VariableDescriptor` instances.
+        """  # noqa: E501
+        result = {"main": []}
+
+        for key, value in cls.__dict__.items():
+            if isinstance(value, VariableDescriptor):
+                result["main"].append(value)
+            elif (
+                isinstance(value, type)
+                and issubclass(value, object)
+                and value is not object
+            ):
+                # Collect descriptors from subcategories
+                subcategory_name = key
+                result[subcategory_name] = [
+                    v
+                    for k, v in value.__dict__.items()
+                    if isinstance(v, VariableDescriptor)
+                ]
+
+        return result
+
+    @classmethod
+    def add(
+        cls, variable: str, dimension: Dimensions, subcategory: str | None = None
+    ) -> None:
+        """
+        Add a variable to the catalog.
+
+        Parameters
+        ----------
+        variable : str
+            The name of the variable (must be uppercase).
+        dimension : Dimensions
+            The dimension of the variable.
+        subcategory: str|None
+            The optional subcategory for the variable.
+
+        Raises
+        ------
+        ValueError
+            The variable name is not uppercase or already exists.
+        """
+        # Validate and transform the variable name
+        transformed_name = _validate_and_transform_variable(variable)
+
+        # Determine the target category (main catalog or subcategory)
+        target = cls
+        if subcategory:
+            # Ensure the subcategory exists as an attribute
+            if not hasattr(cls, subcategory):
+                # Create the subcategory and assign a docstring
+                subcategory_class = type(
+                    subcategory,
+                    (object,),
+                    {
+                        "__doc__": (
+                            f"Dictionary of variable descriptors for {subcategory}-related "
+                            f"quantities."
+                        )
+                    },
+                )
+                setattr(cls, subcategory, subcategory_class)
+            target = getattr(cls, subcategory)
+
+        # Check if the variable already exists in the target category
+        if hasattr(target, variable):
+            raise ValueError(
+                f"Variable name '{variable}' already exists in the '{subcategory or 'main'}' "
+                "catalog. Please choose a unique name."
+            )
+
+        # Add the variable to the target category
+        setattr(target, variable, VariableDescriptor(transformed_name, dimension))
+
+
+# Add custom descriptors
+_D = QuantityDimensions
+fluent_variables = [
+    # velocity
+    # The dominant meaning of helicity comes from
+    # particle physics where it is dimensionless.
+    # In CFD, where it has a different
+    # meaning, it usually has dimension L^2 T^-2.
+    # In Fluent it is L T^-2.
+    ("HELICITY", _D.ACCELERATION),
+    # Lambda 2 criterion is documented as dimensionless
+    # but is T^-2 in Fluent.
+    ("LAMBDA_2_CRITERION", _D.TIME**-2),
+    ("DENSITY_ALL", _D.DENSITY),
+    (
+        "Y_PLUS_BASED_HEAT_TRANSFER_COEFFICIENT",
+        _D.POWER * _D.LENGTH**-2 * _D.TEMPERATURE**-1,
+    ),
+    ("TOTAL_ENTHALPY_DEVIATION", _D.SPECIFIC_ENTHALPY),
+    # residuals
+    ("MASS_IMBALANCE", _D.MASS * _D.TIME**-1),
+    # derivatives
+    ("PRESSURE_HESSIAN_INDICATOR", Dimensions()),
+    ("VELOCITY_ANGLE", _D.ANGLE),
+    ("DVELOCITY_DX", _D.TIME**-1),
+    ("DVELOCITY_DX_MAGNITUDE", _D.TIME**-1),
+    ("DVELOCITY_DX_X", _D.TIME**-1),
+    ("DVELOCITY_DX_Y", _D.TIME**-1),
+    ("DVELOCITY_DX_Z", _D.TIME**-1),
+    ("DVELOCITY_DY", _D.TIME**-1),
+    ("DVELOCITY_DY_MAGNITUDE", _D.TIME**-1),
+    ("DVELOCITY_DY_X", _D.TIME**-1),
+    ("DVELOCITY_DY_Y", _D.TIME**-1),
+    ("DVELOCITY_DY_Z", _D.TIME**-1),
+    ("DVELOCITY_DZ", _D.TIME**-1),
+    ("DVELOCITY_DZ_MAGNITUDE", _D.TIME**-1),
+    ("DVELOCITY_DZ_X", _D.TIME**-1),
+    ("DVELOCITY_DZ_Y", _D.TIME**-1),
+    ("DVELOCITY_DZ_Z", _D.TIME**-1),
+]
+
+for name, dimension in fluent_variables:
+    VariableCatalog.add(name, dimension, "fluent")
+
+
+mesh_variables = [
+    # mesh
+    ("ANISOTROPIC_ADAPTION_CELLS", Dimensions()),
+    ("BOUNDARY_CELL_DISTANCE", Dimensions()),
+    ("BOUNDARY_LAYER_CELLS", Dimensions()),
+    ("BOUNDARY_NORMAL_DISTANCE", Dimensions()),
+    ("BOUNDARY_VOLUME_DISTANCE", Dimensions()),
+    ("CELL_EQUIANGLE_SKEW", Dimensions()),
+    ("CELL_EQUIVOLUME_SKEW", Dimensions()),
+    ("CELL_PARENT_INDEX", Dimensions()),
+    ("CELL_REFINE_LEVEL", Dimensions()),
+    ("CELL_VOLUME", _D.VOLUME),
+    ("CELL_VOLUME_CHANGE", Dimensions()),
+    ("ELEMENT_ASPECT_RATIO", Dimensions()),
+    ("ELEMENT_WALL_DISTANCE", _D.LENGTH),
+    ("FACE_AREA_MAGNITUDE", _D.AREA),
+    ("FACE_HANDEDNESS", Dimensions()),
+    ("INTERFACE_OVERLAP_FRACTION", Dimensions()),
+    ("MARK_POOR_ELEMENTS", Dimensions()),
+    ("SMOOTHED_CELL_REFINE_LEVEL", Dimensions()),
+    ("X_FACE_AREA", _D.AREA),
+    ("Y_FACE_AREA", _D.AREA),
+    ("Z_FACE_AREA", _D.AREA),
+    # cell info
+    ("ACTIVE_CELL_PARTITION", Dimensions()),
+    ("CELL_ELEMENT_TYPE", Dimensions()),
+    ("CELL_ID", Dimensions()),
+    ("CELL_WEIGHT", Dimensions()),
+    ("CELL_ZONE_INDEX", Dimensions()),
+    ("CELL_ZONE_TYPE", Dimensions()),
+    ("PARTITION_NEIGHBOURS", Dimensions()),
+    ("STORED_CELL_PARTITIION", Dimensions()),
+]
+
+for name, dimension in mesh_variables:
+    VariableCatalog.add(name, dimension, "mesh")