docs: use variable catalog (#4025)

Add PyFluent docs showing how to use `VariableCatalog` objects with its
interfaces.

---------

Co-authored-by: pyansys-ci-bot <[email protected]>

Author: seanpearsonuk

doc/changelog.d/4025.documentation.md

@@ -0,0 +1 @@
+use variable catalog

doc/source/user_guide/physical_variables.rst

@@ -0,0 +1,78 @@
+.. _user_guide_variables:
+
+===============================
+Working with physical variables
+===============================
+
+PyFluent integrates with the PyAnsys-units library, which provides a shared catalog of variable objects based on physical quantities like temperature, pressure, and velocity. These variable objects, or VariableDescriptors, can be used throughout PyFluent to reference fields and quantities in a clear, consistent, and reliable way.
+
+Instead of relying on raw strings like ``"temperature"`` or ``"SV_T"``, which may vary between Fluent interfaces or be hard to interpret, you can use named descriptors from the catalog such as ``VariableCatalog``.``TEMPERATURE``). This improves code readability, reduces the chance of errors, and makes it easier to work across different APIs.
+
+The same catalog is designed to work not just with PyFluent, but also with other PyAnsys libraries, offering a unified and expressive way to interact with physical quantities across products.
+
+Overview
+--------
+
+The key benefits of using the ``VariableCatalog`` include:
+
+- Code that is portable across Ansys products and more resistant to typos
+- Simplified refactoring when field names change in Fluent or across versions
+- Integrated dimensional consistency (via ``ansys-units``)
+- Autocompletion and discoverability of supported quantities
+
+Accessing field data
+---------------------
+
+Here’s how to use ``VariableCatalog`` to read and reduce field data using unit-aware quantity references:
+
+.. code-block:: python
+
+    from ansys.fluent.core import launch_fluent, examples
+    from ansys.units.variable_descriptor import VariableCatalog
+
+    solver = launch_fluent()
+    case_path = examples.download_file("mixing_elbow.cas.h5", "pyfluent/mixing_elbow")
+    solver.file.read(file_type="case", file_name=case_path)
+
+    solver.settings.solution.initialization.hybrid_initialize()
+
+    temperature = VariableCatalog.TEMPERATURE
+    locations = ["hot-inlet"]
+
+    # Access scalar field data
+    temp_data = solver.fields.field_data.get_scalar_field_data(
+        field_name=temperature, surfaces=locations
+    )
+    print(temp_data[locations[0]][0])  # value at hot-inlet
+
+    # Compute minimum of a physical quantity
+    temp_min = solver.fields.reduction.minimum(expression=temperature, locations=locations)
+    print(temp_min)
+
+    # Access solution variable data
+    sol_data = solver.fields.solution_variable_data.get_data(
+        solution_variable_name=temperature, zone_names=locations
+    )
+    print(sol_data[locations[0]][0])
+
+Using variables with report definitions
+---------------------------------------
+
+You can also use physical quantities in report definitions to improve clarity and maintainability:
+
+.. code-block:: python
+
+    surface_report = solver.settings.solution.report_definitions.surface["avg_temp"]
+    surface_report.report_type = "surface-areaavg"
+    surface_report.field = temperature  # Note: using VariableCatalog, not a string
+    surface_report.surface_names = locations
+
+    result = solver.solution.report_definitions.compute(report_defs=["avg_temp"])
+    print(result[0]["avg_temp"][0])
+
+Notes
+-----
+
+- All quantities used via ``VariableCatalog`` map to their correct Fluent field identifiers internally.
+- These objects can be validated against their expected dimensional types.
+- ``VariableCatalog`` is part of ``ansys-units``, which is automatically installed with PyFluent.

doc/source/user_guide/user_guide_contents.rst

@@ -16,6 +16,7 @@ User guide
    monitors
    transfer_data
    units
+   physical_variables
    file_transfer
    offline/offline_contents
    convert_journal

doc/styles/config/vocabularies/ANSYS/accept.txt

@@ -82,3 +82,4 @@ venv
 create_workflow
 load_workflow
 codegen
+discoverability