diff --git a/doc/changelog.d/5355.documentation.md b/doc/changelog.d/5355.documentation.md new file mode 100644 index 00000000000..1ed38871ee8 --- /dev/null +++ b/doc/changelog.d/5355.documentation.md @@ -0,0 +1 @@ +Improve PyFluent docs discoverability diff --git a/doc/source/_templates/layout.html b/doc/source/_templates/layout.html new file mode 100644 index 00000000000..3115912c927 --- /dev/null +++ b/doc/source/_templates/layout.html @@ -0,0 +1,17 @@ +{# + Inject a canonical link pointing at the equivalent page in the `stable` + version of the docs. This consolidates ranking signal across the many + versioned builds (/version/0.14/, /version/dev/, /version/stable/, ...) + onto a single authoritative URL per page. + + See pyfluent-doc-plan.md §4. +#} +{% extends "!layout.html" %} + +{% block extrahead %} + {{ super() }} + {%- if pagename %} + + {%- endif %} +{% endblock %} diff --git a/doc/source/cheatsheet/index.rst b/doc/source/cheatsheet/index.rst new file mode 100644 index 00000000000..085068c6743 --- /dev/null +++ b/doc/source/cheatsheet/index.rst @@ -0,0 +1,303 @@ +.. _ref_pyfluent_cheat_sheet: + +PyFluent cheat sheet +==================== + +A quick reference to the most common PyFluent commands for launching Ansys +Fluent from Python, importing a mesh, defining materials, defining boundary +conditions, modifying cell zone conditions, applying solution settings, and +accessing field data. A printable PDF version is also available from the +sidebar of the docs. + +.. contents:: Quick reference + :local: + :depth: 2 + + +Quick start +----------- + +Import PyFluent and the settings API objects most workflows need: + +.. code-block:: python + + import ansys.fluent.core as pyfluent + from ansys.units import VariableCatalog as VC + from ansys.fluent.core import ( + ScalarFieldDataRequest, + VectorFieldDataRequest, + SurfaceFieldDataRequest, + SurfaceDataType, + ) + from ansys.fluent.core.solver import * + + +Launching Fluent +---------------- + +Launch a solver or meshing session +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: python + + solver = pyfluent.Solver.from_install() + meshing = pyfluent.Meshing.from_install() + +Connect to an existing Fluent session +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: python + + session = pyfluent.Solver.from_connection(ip, port, password) + + +Reading and writing case and data files +--------------------------------------- + +.. code-block:: python + + ReadCase(settings_source=solver)(file_name="") + ReadCaseData(settings_source=solver)(file_name="") + + WriteCase(settings_source=solver)(file_name="") + WriteCaseData(settings_source=solver)(file_name="") + + +Importing a mesh (watertight geometry workflow) +----------------------------------------------- + +.. code-block:: python + + watertight = meshing.watertight() + + import_geom = watertight.import_geometry + import_geom.file_name = "" + import_geom.length_unit = "mm" + import_geom() + + surf_mesh = watertight.create_surface_mesh + surf_mesh.cfd_surface_mesh_controls.max_size = 0.3 + surf_mesh() + + watertight.describe_geometry.setup_type = "fluid" + watertight.describe_geometry() + + volume_mesh = watertight.create_volume_mesh_wtm + volume_mesh.volume_fill = "poly-hexcore" + volume_mesh() + + +Defining boundary conditions +---------------------------- + +Set a velocity inlet with turbulence and thermal conditions using the +settings API: + +.. code-block:: python + + inlet = VelocityInlet(solver, name="cold-inlet") + inlet.momentum.velocity_magnitude = 0.4 + + turbulence = inlet.turbulence + turbulence = ( + turbulence.turbulence_specification.INTENSITY_AND_HYDRAULIC_DIAMETER + ) + turbulence.turbulent_intensity = 0.05 + turbulence.hydraulic_diameter = "4 [in]" + + inlet.thermal.temperature = 293.15 + + +Defining materials +------------------ + +.. code-block:: python + + materials = Materials(solver) + air_copy = materials.fluid.make_a_copy(from_="air", to="air-copied") + materials.fluid["air-copied"].viscosity = 1.81e-05 + + # Create a new solid material + my_solid = materials.solid.create("my-solid") + my_solid.density.value = 2650 + my_solid.thermal_conductivity.value = 7.6 + + +Modifying cell zone conditions +------------------------------ + +.. code-block:: python + + cell_zones = CellZoneConditions(solver) + cell_zones.fluid["elbow-fluid"].general.material = "air-copied" + + +Enabling physics models +----------------------- + +Energy, viscous turbulence, radiation, and species transport models: + +.. code-block:: python + + models = Models(solver) + models.energy.enabled = True + models.energy.viscous_dissipation = True + + viscous = Viscous(solver) + viscous.model = viscous.model.K_EPSILON + k_epsilon_model = viscous.k_epsilon_model + k_epsilon_model = k_epsilon_model.REALIZABLE + + rad = Radiation(solver) + rad.model = rad.model.MONTE_CARLO + rad.solve_frequency.number_of_histories = 1e7 + + species = Species(solver).model.option + species = species.SPECIES_TRANSPORT + + +Applying solution settings +-------------------------- + +Configure solution methods: + +.. code-block:: python + + soln = Solution(solver) + + methods = soln.methods + methods.p_v_coupling.flow_scheme = "Coupled" + + grad_scheme = methods.spatial_discretization.gradient_scheme + grad_scheme = grad_scheme.GREEN_GAUSS_NODE_BASED + +Define surface report definitions: + +.. code-block:: python + + rep_defs = ReportDefinitions(solver) + rep_defs.surface["outlet-temp-avg"] = {} + + soln_report_type = rep_defs.surface["outlet-temp-avg"].report_type + soln_report_type = soln_report_type.SURFACE_AREA + + rep_defs.surface["outlet-temp-avg"].field = VC.TEMPERATURE + +Initialize and run the calculation: + +.. code-block:: python + + initialization = Initialization(solver) + init_type = initialization.initialization_type + init_type = init_type.HYBRID + + Initialize(solver)() + + run_calc = RunCalculation(solver) + run_calc.parameters.iter_count = 100 + + Iterate(solver)() + + Monitor(solver).residual.plot() + + +Accessing field data +-------------------- + +Request scalar, vector, and surface field data from the solver: + +.. code-block:: python + + field_data = solver.fields.field_data + + abs_press_req = ScalarFieldDataRequest( + field_name=VC.ABSOLUTE_PRESSURE, surfaces=["cold-inlet"] + ) + abs_pressure = field_data.get_field_data(abs_press_req) + + vel_req = VectorFieldDataRequest( + field_name=VC.VELOCITY, surfaces=["cold-inlet"] + ) + velocity = field_data.get_field_data(vel_req) + + surf_req = SurfaceFieldDataRequest( + data_types=[SurfaceDataType.Vertices, SurfaceDataType.FacesCentroid], + surfaces=["hot-inlet", "cold-inlet"], + ) + surfaces = field_data.get_field_data(surf_req) + vertices = surfaces["cold-inlet"].vertices + centroids = surfaces["hot-inlet"].face_centroids + +Query field metadata (allowed values, active status, ranges): + +.. code-block:: python + + scalar_fields = field_data.scalar_fields + vector_fields = field_data.vector_fields + surface_fields = field_data.surfaces + + scalar_names = scalar_fields.allowed_values() + vector_names = vector_fields.allowed_values() + surface_names = surface_fields.allowed_values() + + temp_active = scalar_fields.is_active(VC.TEMPERATURE) + vel_active = vector_fields.is_active(VC.VELOCITY) + + temp_range = scalar_fields.range(VC.TEMPERATURE) + vmag_range = scalar_fields.range(VC.VELOCITY_MAGNITUDE) + + +Reduction functions +------------------- + +Compute area, volume, averages, integrals, forces, and extrema over boundary +locations: + +.. code-block:: python + + reduction = solver.fields.reduction + velocity_inlet = VelocityInlet(solver, name="cold-inlet") + pressure_outlet = PressureOutlet(solver, name="outlet") + wall = WallBoundary(solver, name="wall-elbow") + + area = reduction.area(locations=[velocity_inlet]) + volume = reduction.volume(locations=[velocity_inlet]) + + avg_pressure = reduction.area_average( + VC.ABSOLUTE_PRESSURE, locations=[pressure_outlet] + ) + total_mass = reduction.mass_integral( + VC.ABSOLUTE_PRESSURE, locations=[pressure_outlet] + ) + + force = reduction.force(locations=[wall]) + max_vel = reduction.maximum(VC.VELOCITY_MAGNITUDE, locations=[wall]) + + +Solution variables +------------------ + +Read and write raw solution variable data by zone and domain: + +.. code-block:: python + + sv_info = solver.fields.solution_variable_info + sv_data = solver.fields.solution_variable_data + + zones_info = sv_info.get_zones_info() + temp_data = sv_data.get_data( + variable_name=VC.TEMPERATURE, + zone_names=["elbow-fluid"], + domain_name="mixture", + ) + + temp_array = sv_data.create_empty_array( + VC.TEMPERATURE, "elbow-fluid", "mixture" + ) + temp_array[:] = 500 + + sv_data.set_data( + variable_name=VC.TEMPERATURE, + zone_names_to_data={"elbow-fluid": temp_array}, + domain_name="mixture", + ) diff --git a/doc/source/conf.py b/doc/source/conf.py index 76df4fb958f..244d1a140cc 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -38,10 +38,17 @@ "sphinx_autodoc_typehints", "sphinx_copybutton", "sphinx_design", + "sphinx_sitemap", "sphinxemoji.sphinxemoji", "sphinx_toggleprompt", ] +# Canonical base URL used by sphinx-sitemap and by search engines to +# consolidate ranking signal onto the `stable` version of the docs. +# See pyfluent-doc-plan.md §4 and §5. +html_baseurl = "https://fluent.docs.pyansys.com/version/stable/" +sitemap_url_scheme = "{link}" + toggleprompt_offset_right = 35 if os.getenv("PYFLUENT_DOC_SKIP_EXAMPLES") != "1": diff --git a/doc/source/index.rst b/doc/source/index.rst index 25cf5c3a956..d6fb65a3a75 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -7,6 +7,7 @@ PyFluent documentation |version| getting_started/getting_started_contents user_guide/user_guide_contents + cheatsheet/index api/api_contents examples/index contributing/contributing_contents @@ -50,6 +51,8 @@ Getting started --------------- Get started with PyFluent by following the steps in the :ref:`getting_started` guide. +For a one-page reference of the most common commands, see the +:ref:`PyFluent cheat sheet `. Resources diff --git a/pyproject.toml b/pyproject.toml index eb1dcfbb9fe..1fa863019f0 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -74,6 +74,7 @@ docs = [ "sphinx-copybutton==0.5.2", "sphinx-gallery==0.21.0", "sphinx-notfound-page==1.1.0", + "sphinx-sitemap==2.6.0", "sphinxcontrib-websupport==2.0.0", "sphinx_design==0.6.1", "sphinxemoji==0.3.2",