docs: direct settings object format (#3418)

* docs: New format settings

* docs: FluidCellZoneCondition

* docs: VelocityInlet

* docs: settings objects

* docs: Battery

* docs: old -> new

doc/source/user_guide/solver_settings/index.rst

@@ -2,28 +2,53 @@
 
 Solver settings objects
 =======================
-Solver settings objects provide a natural way to access and modify Fluent solver
-settings and issue commands to be executed in the Fluent solver.
 
-Accessing solver settings
--------------------------
+.. vale Google.Spacing = NO
+
+Solver settings objects provide a natural way to access and modify Fluent solver
+settings and issue commands to be executed in the Fluent solver. 
 An appropriate call to the :func:`~ansys.fluent.core.launcher.launcher.launch_fluent`
-function returns an object (named :ref:`solver <ref_root>` in
-the following code snippets) whose interface directly exposes the
-:ref:`ref_root` of the solver settings hierarchy.
+function returns an object whose interface directly exposes the :ref:`ref_root` of the solver settings hierarchy.
+
+.. vale Google.Spacing = YES
 
-.. code:: python
+
+New format for accessing solver settings objects
+------------------------------------------------
+
+To simplify the usage of Fluent solver settings and improve readability, 
+you can now instantiate settings objects directly using a more intuitive syntax. 
+This new approach allows for straightforward access to various settings without 
+navigating through the hierarchical structure of the solver settings.
+
+Example usage
+-------------
+
+.. code-block:: python
 
   >>> import ansys.fluent.core as pyfluent
   >>> solver = pyfluent.launch_fluent(mode=pyfluent.FluentMode.SOLVER)
+  >>> inlet1 = pyfluent.VelocityInlet(settings_source=solver, name="inlet-1")
+
+
+This format provides a more natural way to create and interact with settings objects, 
+making your code easier to read and maintain. By abstracting the underlying hierarchy, 
+users can focus on the specific settings they need without dealing with potential changes 
+in the Fluent API structure.
+
+Accessing solver settings
+-------------------------
+
+Following the introduction of the new format, the traditional method remains available for those 
+who prefer the existing hierarchy.
+
+.. code-block:: python
+
   >>> file = solver.settings.file
   >>> setup = solver.settings.setup
   >>> solution = solver.settings.solution
   >>> results = solver.settings.results
 
-Note that the last three are top-level nodes in the outline tree view in Fluent's graphical 
-user interface (GUI) --- much of this settings hierarchy has been designed in close alignment with this GUI hierarchy.
-
 
 Types of settings objects
 -------------------------
@@ -74,20 +99,25 @@ as a dictionary for ``Group`` and ``NamedObject`` types or as a list for ``ListO
 
 .. code-block::
 
-  >>> solver.settings.setup.models.viscous.model()
+  >>> import ansys.fluent.core as pyfluent
+  >>> viscous = pyfluent.Viscous(settings_source=solver)
+  >>> viscous.model()
   'k-epsilon-standard'
 
 
 .. code-block::
 
+  >>> import ansys.fluent.core as pyfluent
+  >>> energy = pyfluent.Energy(settings_source=solver)
   >>> from pprint import pprint
-  >>> pprint (solver.settings.setup.models.energy(), width=1)
+  >>> pprint (energy(), width=1)
   {'enabled': True,
    'inlet_diffusion': True,
    'kinetic_energy': False,
    'pressure_work': False,
    'viscous_dissipation': False}
-  >>> solver.settings.setup.boundary_conditions.velocity_inlet['inlet1'].vmag.constant()
+  >>> inlet1 = pyfluent.VelocityInlet(settings_source=solver, name="inlet1")
+  >>> inlet1.vmag.constant()
   10.0
 
 
@@ -98,9 +128,13 @@ and ``NamedObject`` types, the state value is a dictionary. For the
 
 .. code-block::
 
-  >>> solver.settings.setup.models.viscous.model = 'laminar'
-  >>> solver.settings.setup.models.energy = { 'enabled' : False }
-  >>> solver.settings.setup.boundary_conditions.velocity_inlet['inlet1'].vmag.constant = 14
+  >>> import ansys.fluent.core as pyfluent
+  >>> viscous = pyfluent.Viscous(settings_source=solver)
+  >>> viscous.model = 'laminar'
+  >>> energy = pyfluent.Energy(settings_source=solver)
+  >>> energy = { 'enabled' : False }
+  >>> inlet1 = pyfluent.VelocityInlet(settings_source=solver, name="inlet1")
+  >>> inlet1.vmag.constant = 14
 
 
 You can also access the state of an object with the ``get_state()`` method and
@@ -130,7 +164,9 @@ You can print the current state in a simple text format with the
 
 .. code-block::
 
-  >>> solver.settings.setup.models.print_state()
+  >>> import ansys.fluent.core as pyfluent
+  >>> models = pyfluent.Models(settings_source=solver)
+  >>> models.print_state()
 
 
 The following output is returned:
@@ -182,19 +218,25 @@ for that object or returns ``None`` otherwise.
 
 .. code-block::
 
-  >>> solver.settings.setup.models.viscous.model.allowed_values()
+  >>> import ansys.fluent.core as pyfluent
+  >>> viscous = pyfluent.Viscous(settings_source=solver)
+  >>> viscous.model.allowed_values()
   ['inviscid', 'laminar', 'k-epsilon-standard', 'k-omega-standard', 'mixing-length', 'spalart-allmaras', 'k-kl-w', 'transition-sst', 'reynolds-stress', 'scale-adaptive-simulation', 'detached-eddy-simulation', 'large-eddy-simulation']
 
 
 .. code-block::
 
-  >>> solver.settings.setup.models.viscous.model.get_attr('allowed-values')
+  >>> import ansys.fluent.core as pyfluent
+  >>> viscous = pyfluent.Viscous(settings_source=solver)
+  >>> viscous.model.get_attr('allowed-values')
   ['inviscid', 'laminar', 'k-epsilon-standard', 'k-omega-standard', 'mixing-length', 'spalart-allmaras', 'k-kl-w', 'transition-sst', 'reynolds-stress', 'scale-adaptive-simulation', 'detached-eddy-simulation', 'large-eddy-simulation']
 
 
 .. code-block::
 
-  >>> solver.settings.setup.models.viscous.model.get_attrs(['allowed-values'])
+  >>> import ansys.fluent.core as pyfluent
+  >>> viscous = pyfluent.Viscous(settings_source=solver)
+  >>> viscous.model.get_attrs(['allowed-values'])
   {'allowed-values': ['inviscid', 'laminar', 'k-epsilon', 'k-omega', 'mixing-length', 'spalart-allmaras', 'k-kl-w', 'transition-sst', 'reynolds-stress', 'scale-adaptive-simulation', 'detached-eddy-simulation', 'large-eddy-simulation']}
 
 
@@ -261,12 +303,13 @@ in a single solver session:
   >>> solver.settings.file.read(file_type="case", file_name=import_file_name)
   Fast-loading...
   ...Done
-  >>> solver.settings.setup.models.viscous.is_active()
+  >>> viscous = pyfluent.Viscous(settings_source=solver)
+  >>> viscous.is_active()
   True
-  >>> solver.settings.setup.models.viscous.model.is_read_only()
+  >>> viscous.model.is_read_only()
   False
-  >>> solver.settings.setup.models.viscous.model.default_value()
-  >>> pprint(solver.settings.setup.models.viscous.model.allowed_values(), width=1)
+  >>> viscous.model.default_value()
+  >>> pprint(viscous.model.allowed_values(), width=1)
   ['inviscid',
    'laminar',
    'k-epsilon',
@@ -279,9 +322,10 @@ in a single solver session:
    'scale-adaptive-simulation',
    'detached-eddy-simulation',
    'large-eddy-simulation']
-  >>> solver.settings.setup.boundary_conditions.velocity_inlet['cold-inlet'].turb_intensity.min()
+  >>> cold_inlet = pyfluent.VelocityInlet(settings_source=solver, name="cold-inlet")
+  >>> cold_inlet.turb_intensity.min()
   0
-  >>> solver.settings.setup.boundary_conditions.velocity_inlet['cold-inlet'].turb_intensity.max()
+  >>> cold_inlet.turb_intensity.max()
   1
 
 
@@ -294,7 +338,9 @@ is currently active.
 The ``get_active_child_names()`` method returns a list of
 active children::
 
-  >>> solver.settings.setup.models.get_active_child_names()
+  >>> import ansys.fluent.core as pyfluent
+  >>> models = pyfluent.Models(settings_source=solver)
+  >>> models.get_active_child_names()
   ['energy', 'multiphase', 'viscous']
 
 The ``get_active_command_names()`` method returns the list of active
@@ -303,17 +349,21 @@ commands::
   >>> solver.settings.solution.run_calculation.get_active_command_names()
   ['iterate']
 
-Supporting wildcards
---------------------
+Wildcards
+---------
 You can use wildcards when using named objects, list objects, and string list settings.
 For named objects and list objects, for instance::
 
-  >>> solver.settings.setup.cell_zone_conditions.fluid["*"].source_terms["*mom*"]()
+  >>> import ansys.fluent.core as pyfluent
+  >>> fluid = pyfluent.FluidCellZone(settings_source=solver, name="*")
+  >>> fluid.source_terms["*mom*"]()
   {'fluid': {'source_terms': {'x-momentum': [], 'y-momentum': [], 'z-momentum': []}}}
 
 Also, when you have one or more velocity inlets with "inlet" in their names::
 
-  >>> solver.settings.setup.boundary_conditions.velocity_inlet["*inlet*"].vmag()
+  >>> import ansys.fluent.core as pyfluent
+  >>> inlet = pyfluent.VelocityInlet(settings_source=solver, name="*inlet*")
+  >>> inlet.vmag()
   {'velo-inlet_2': {'vmag': {'option': 'value', 'value': 50}},
   'velo-inlet_1': {'vmag': {'option': 'value', 'value': 35}}
 

doc/source/user_guide/solver_settings/set_up/boundary_conditions.rst

@@ -13,7 +13,7 @@ Boundary conditions
     >>> file_name = examples.download_file("mixing_elbow.cas.h5", "pyfluent/mixing_elbow")
     >>> solver = pyfluent.launch_fluent()
     >>> solver.settings.file.read_case(file_name=file_name)
-    >>> cold_inlet = solver.settings.setup.boundary_conditions.velocity_inlet["cold-inlet"]
+    >>> cold_inlet = pyfluent.VelocityInlet(settings_source=solver, name="cold-inlet")
     >>> cold_inlet.momentum.velocity.set_state(0.4)
     >>> inlet_turbulence = cold_inlet.turbulence
     >>> turbulence_specification = inlet_turbulence.turbulence_specification
@@ -33,4 +33,5 @@ Cell zone conditions
 
 .. code:: python
 
-    >>> solver.settings.setup.cell_zone_conditions.fluid["elbow-fluid"].laminar.set_state(True)
+    >>> elbow_fluid = pyfluent.FluidCellZone(settings_source=solver, name="elbow-fluid")
+    >>> elbow_fluid.laminar.set_state(True)

doc/source/user_guide/solver_settings/set_up/materials.rst

@@ -12,7 +12,7 @@ Copy material from database
     >>> file_name = examples.download_file("mixing_elbow.cas.h5", "pyfluent/mixing_elbow")
     >>> solver = pyfluent.launch_fluent()
     >>> solver.settings.file.read_case(file_name=file_name)
-    >>> materials = solver.settings.setup.materials
+    >>> materials = pyfluent.Materials(settings_source=solver)
     >>> fluids = materials.fluid
     >>> fluids.make_a_copy(from_="air",to="air-2")
     >>> air_copy = fluids["air-2"]
@@ -34,7 +34,8 @@ Copy material from database
      'sutherland',
      'kinetic-theory']
     >>> air_copy.viscosity.value.set_state(1.81e-05)
-    >>> solver.settings.setup.cell_zone_conditions.fluid["elbow-fluid"].material.set_state("air-2")
+    >>> elbow_fluid = pyfluent.FluidCellZone(settings_source=solver, name="elbow-fluid")
+    >>> elbow_fluid.material.set_state("air-2")
 
 
 Create new material

doc/source/user_guide/solver_settings/set_up/models/battery.rst

@@ -6,7 +6,8 @@ Setting up and querying the model
 
 .. code:: python
 
-    >>> battery = solver.settings.setup.models.battery
+    >>> import ansys.fluent.core as pyfluent
+    >>> battery = pyfluent.Battery(settings_source=solver)
     >>> battery.enabled.set_state(True)
     >>> battery.solution_method.allowed_values()
     ['cht-coupling', 'fmu-cht-coupling', 'circuit-network', 'msmd', 'msmd-rom']

doc/source/user_guide/solver_settings/set_up/models/dpm.rst

@@ -6,7 +6,8 @@ Setting up and querying the model
 
 .. code:: python
 
-    >>> dpm = solver.settings.setup.models.discrete_phase
+    >>> import ansys.fluent.core as pyfluent
+    >>> dpm = pyfluent.DiscretePhase(settings_source=solver)
     >>> dpm_models = dpm.physical_models
     >>> dpm_models.virtual_mass_force.enabled.get_state()
     >>> dpm_models.virtual_mass_force.virtual_mass_factor.is_active()

doc/source/user_guide/solver_settings/set_up/models/energy.rst

@@ -11,7 +11,7 @@ Setting up and querying the model
     >>> file_name = examples.download_file("mixing_elbow.cas.h5", "pyfluent/mixing_elbow")
     >>> solver = pyfluent.launch_fluent()
     >>> solver.settings.file.read_case(file_name=file_name)
-    >>> energy = solver.settings.setup.models.energy
+    >>> energy = pyfluent.Energy(settings_source=solver)
     >>> energy.enabled.get_state()
     True
     >>> from pprint import pprint

doc/source/user_guide/solver_settings/set_up/models/radiation.rst

@@ -6,7 +6,8 @@ Setting up and querying the model
 
 .. code:: python
 
-    >>> radiation = solver.settings.setup.models.radiation
+    >>> import ansys.fluent.core as pyfluent
+    >>> radiation = pyfluent.Radiation(settings_source=solver)
     >>> from pprint import pprint
     >>> pprint(radiation.get_state(), width=1)
     {'model': 'none',

doc/source/user_guide/solver_settings/set_up/models/species.rst

@@ -6,8 +6,9 @@ Setting up and querying the model
 
 .. code:: python
 
+    >>> import ansys.fluent.core as pyfluent
     >>> solver.settings.file.read_case(file_name=file_name)
-    >>> species = solver.settings.setup.models.species
+    >>> species = pyfluent.Species(settings_source=solver)
     >>> species.get_state()
     {'model': {'option': 'off', 'number_vol_spec': False}}
     >>> from pprint import pprint

doc/source/user_guide/solver_settings/set_up/models/viscous.rst

@@ -6,7 +6,8 @@ Setting up and querying the model
 
 .. code:: python
 
-    >>> viscous = solver.settings.setup.models.viscous
+    >>> import ansys.fluent.core as pyfluent
+    >>> viscous = pyfluent.Viscous(settings_source=solver)
     >>> from pprint import pprint
     >>> pprint(viscous.get_state(), width=1)
     {'k_omega_model': 'sst',