Overview
Ansys Fluent is powerful computational fluid dynamics software, and PyFluent is a Python library of remotable APIs for interacting with Ansys Fluent. PyFluent provides an interface for automating, customizing, and streamlining CFD workflows using the flexibility and power of Python.
This blog post offers an overview of the Settings APIs and objects available in PyFluent to help you understand how to effectively utilize them to develop PyFluent workflows.
Settings APIs and objects
You use the Settings APIs and objects to set up simulation workflows in a Pythonic way. The let you configure various aspects of the simulation, such as the solver settings, materials, boundary conditions, physical models, solution settings, and results postprocessing settings.
The Settings APIs and objects are categorized into different groups based on their functionality. The following figure shows the Ansys Fluent Outline View and categorization.
This categorization is reflected in PyFluent as well. These APIs are organized into different modules, each corresponding to a specific category of Settings, which can be easily accessed using the child_names and command_names attributes on these objects.
child_names: An object property for retrieving the list of the names of the child's objects.command_names: An object property for getting the list of the commands (methods) available for a given object.
Detailed examples demonstrate the use of these properties follow.
You can also access the Settings APIs, objects, and object properties within the Ansys Fluent interface using the PyConsole.
Examples
1. Access the Settings APIs and objects
The solver is a top-level object. Here is how you access the solver.settings object and its child names:
# import the necessary libraries
import ansys.fluent.core as pyfluent
# Import the examples module to download example files
from ansys.fluent.core import examples
# Import the necessary enums for precision and UI mode
from ansys.fluent.core import Precision, UIMode
import_file_name = examples.download_file(
"mixing_elbow.msh.h5", "pyfluent/mixing_elbow"
)
# Launch Fluent with desired options
solver = pyfluent.launch_fluent(
precision=Precision.DOUBLE,
processor_count=2,
mode="solver",
ui_mode=UIMode.GUI,
)
print(solver.get_fluent_version())
This API launches the Fluent session and provides access to the solver object. Now access the solver's settings object and its child:
# Access the solver settings object
solver_settings = solver.settings.child_names # returns list
print(solver_settings)
# Output
['file', 'mesh', 'server', 'setup', 'solution', 'results', 'design', 'parametric_studies', 'current_parametric_study', 'parameters', 'parallel', 'transient_post_processing']
The output from the above API execution provides a list of child names of the solver.settings object. These child names correspond to specific categories or sections in the Fluent GUI, such as setup, solution, and results, letting you map the API output directly to the GUI structure for easier navigation and configuration.
The solver has the file object as child. This is how you access its child's names:
file_objects = solver.settings.file.child_names
print(file_objects)
# Output
['single_precision_coordinates', 'binary_legacy_files', 'cff_files', 'auto_merge_zones', 'convert_hanging_nodes_during_read', 'async_optimize', 'write_pdat', 'auto_save', 'export', 'import_', 'parametric_project', 'cffio_options', 'batch_options', 'interpolate', 'table_file_manager']
The output shows the available child objects on the file object. It has additional child objects, which you use to configure the file settings in Fluent for specific purposes. This code shows how to configure export settings:
export_settings = solver.settings.file.export.settings.child_names
print(export_settings)
# Output
['cgns_export_filetype', 'cgns_mesh_type', 'cgns_polyhedral_cpu_threads', 'cgns_merge_ngons_to_single_ngon', 'cgns_default_cellsize_changes', 'cgns_enhance_poly_export_performance', 'cgns_familyname', 'cgns_separate_cellzones']
The output lists the available settings for the export.settings object, which you can further use to configure the export settings in Fluent.
The file object also has a command_names property, which lists the available commands (methods) on the file object.
file_commands = solver.settings.file.command_names
print(file_commands)
# Output
['define_macro', 'execute_macro', 'read_macros', 'read', 'read_case', 'read_case_data', 'read_case_setting', 'read_data', 'read_mesh', 'read_surface_mesh', 'read_journal', 'start_journal', 'start_python_journal', 'stop_journal', 'replace_mesh', 'write', 'write_case', 'write_data', 'write_case_data', 'read_settings', 'read_field_functions', 'read_injections', 'read_profile', 'read_pdf', 'read_isat_table', 'show_configuration', 'stop_macro', 'start_transcript', 'stop_transcript', 'data_file_options', 'beta_settings']
The output contains available methods on the file object, which you can use to perform various file operations in Fluent, such as reading and writing case and data files, executing macros, and managing settings.
To read the case and data files, you use the read_case_data command, passing a file name as an argument:
solver.settings.file.read_case_data(file_name = import_file_name)
You can access detailed help on the command (method) using help(solver.settings.file.read_mesh). In
addition to information about the command, the help provides argument and usage information.
help(solver.settings.file.read_case_data)
Also, PyFluent provides a property for checking the required arguments for a given command using the argument_names property.
solver.settings.file.read_mesh.argument_names
# Output
['file_name', 'pdf_file_name']
The output lists the required arguments for the read_case_data command, which you can use to read the case and data files in Fluent.
However, the discussed properties list all child names and command names (methods) available on the object, which can be overwhelming. To get only active child names and command names, use the get_active_child_names() and get_active_command_names() methods on the Settings objects, respectively.
There are many other methods and properties available on the Settings objects, such as get_state(), set_state(), print_state(), allowed_values(), min(), and max(). You can use them to get or set the state of the object, print the current state of the object, get the allowed values for a given command, and get the minimum and maximum values for a given object.
e.g.,
solver.settings.setup.models.viscous.model.allowed_values()
# Output
['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']
Similarly, you can access other objects, their child names, command names, allowed values, and more using this same approach.
The following example shows how to access the setup object and its child names, further access the models object and its child names, and enable the energy model.
setup_obj = solver.settings.setup.child_names
print(setup_obj)
# Output
['general', 'models', 'materials', 'cell_zone_conditions', 'model_topology', 'physics', 'boundary_conditions', 'mesh_interfaces', 'dynamic_mesh', 'reference_values', 'reference_frames', 'named_expressions', 'turbo_models', 'user_defined', 'profiles']
As indicated by the output, the setup object contains models as one of its child objects. Here is how you access the models object and view the name of its children:
models_obj = solver.settings.setup.models.child_names
print(models_obj)
# Output
['multiphase', 'energy', 'viscous', 'acoustics', 'radiation', 'species', 'discrete_phase', 'virtual_blade_model', 'optics', 'structure', 'ablation', 'dsmc', 'echemistry', 'battery', 'system_coupling', 'sofc', 'pemfc']
The output shows the available models in the models object, which can be used to configure various physical models in Fluent. The energy model can be accessed as follows:
print(solver.settings.setup.models.energy.child_names)
# Output
['enabled', 'viscous_dissipation', 'pressure_work', 'kinetic_energy', 'inlet_diffusion', 'two_temperature']
The output lists the available child names of the energy model object, which you can use to configure the energy model in Fluent.
Print the current settings of the energy model object using the print_state() method:
print(solver.settings.setup.models.energy.print_state())
# Output
enabled : False
The output shows that the enabled object is currently set to False, indicating that the energy model is disabled. To enable the energy model, the enabled object should be set to True (a Boolean value).
To enable the energy model, set the enabled object to True:
solver.settings.setup.models.energy.enabled = True
This command sets the enabled object of the energy model to True, enabling the energy model in Fluent.
To verify that the energy model is enabled, print the current state of the energy model object again:
print(solver.settings.setup.models.energy.print_state())
# Output
enabled : True
viscous_dissipation : False
pressure_work : False
kinetic_energy : False
inlet_diffusion : True
This very basic example shows you how to accomplish the following:
- Access the Settings APIs and objects in PyFluent.
- Use these APIs and objects to configure the simulation setup.
- Understand the hierarchy of the objects and APIs available in PyFluent with respect to the Ansys Fluent user interface.
Summary
This blog discussed the Settings APIs and objects in PyFluent, which provide APIs to configure various aspects of CFD simulations in Ansys Fluent. The examples demonstrated how to access these APIs, retrieve child names and command names, and use them to set up simulation.
The hierarchical structure of settings in PyFluent, which mirrors the Ansys Fluent GUI, was highlighted, along with practical examples of interacting with these Settings objects and their properties programmatically. This understanding is essential for automating and customizing CFD workflows effectively using PyFluent.
The blog should help you to understand how to use the Settings APIs and objects in PyFluent effectively for developing PyFluent workflows.