.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "auto_tutorials/example_01_dictionaries.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_auto_tutorials_example_01_dictionaries.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_auto_tutorials_example_01_dictionaries.py:


Read, modify, and write OpenFOAM dictionaries
=============================================

This tutorial covers how to:

- read an OpenFOAM dictionary file from disk into a Python object,
- pull typed values out of it (``Word``, ``float``, sub-dictionaries),
- change a value, and
- write the dictionary back to disk in OpenFOAM format.

Prerequisites
-------------

- OpenFOAM v2312+ sourced (``source /path/to/OpenFOAM/etc/bashrc``).
- pybFoam installed (``pip install pybFoam[all]``).

.. GENERATED FROM PYTHON SOURCE LINES 20-25

Set up a working case
---------------------
:func:`pybFoam.clone_example` copies a baseline case from the repo's
``examples/`` folder into a tmp directory and restores ``0.orig/``
→ ``0/``. The original on-disk case is never touched.

.. GENERATED FROM PYTHON SOURCE LINES 25-31

.. code-block:: Python


    from pybFoam import clone_example

    case = clone_example("cavity")
    print(f"case = {case}")





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    case = /tmp/pybfoam_47qxo1jm/cavity




.. GENERATED FROM PYTHON SOURCE LINES 32-38

Read a dictionary
-----------------
:func:`pybFoam.dictionary.read` parses an OpenFOAM dictionary into a
Python object. ``get[T]`` is templated on the expected return type —
the same accessor handles scalars, words, vectors, and field
entries; a wrong type raises immediately at the call site.

.. GENERATED FROM PYTHON SOURCE LINES 38-49

.. code-block:: Python


    from pybFoam import Word, dictionary

    control_dict_path = case / "system" / "controlDict"
    d = dictionary.read(str(control_dict_path))

    print("application :", d.get[Word]("application"))
    print("startTime   :", d.get[float]("startTime"))
    print("endTime     :", d.get[float]("endTime"))
    print("deltaT      :", d.get[float]("deltaT"))





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    application : icoFoam
    startTime   : 0.0
    endTime     : 0.5
    deltaT      : 0.0005




.. GENERATED FROM PYTHON SOURCE LINES 50-52

Enumerate the top-level keys with ``dictionary.toc``. Use this
to introspect any dictionary you didn't write yourself.

.. GENERATED FROM PYTHON SOURCE LINES 52-57

.. code-block:: Python


    print("top-level keys:")
    for key in d.toc():
        print(f"  - {key}")





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    top-level keys:
      - FoamFile
      - application
      - startFrom
      - startTime
      - stopAt
      - endTime
      - deltaT
      - writeControl
      - writeInterval
      - purgeWrite
      - writeFormat
      - writePrecision
      - writeCompression
      - timeFormat
      - timePrecision
      - runTimeModifiable




.. GENERATED FROM PYTHON SOURCE LINES 58-63

Modify and write it back
------------------------
``dictionary.set`` updates an entry in place. ``dictionary.write``
serialises the whole dictionary back to disk in OpenFOAM format. We
write to a sibling path so we can compare before/after.

.. GENERATED FROM PYTHON SOURCE LINES 63-70

.. code-block:: Python


    modified_path = case / "system" / "controlDict.modified"

    d.set("endTime", 0.05)
    d.set("deltaT", 0.005)
    d.write(str(modified_path))








.. GENERATED FROM PYTHON SOURCE LINES 71-73

The round-trip via disk proves the values were actually written —
not just held in the in-memory dictionary object.

.. GENERATED FROM PYTHON SOURCE LINES 73-78

.. code-block:: Python


    d_modified = dictionary.read(str(modified_path))
    print("endTime (modified) :", d_modified.get[float]("endTime"))
    print("deltaT  (modified) :", d_modified.get[float]("deltaT"))





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    endTime (modified) : 0.05
    deltaT  (modified) : 0.005




.. GENERATED FROM PYTHON SOURCE LINES 79-81

Skim the output file directly to see what an OpenFOAM dictionary
looks like on disk (``set`` preserves OpenFOAM's syntax).

.. GENERATED FROM PYTHON SOURCE LINES 81-84

.. code-block:: Python


    for line in modified_path.read_text().splitlines()[-20:]:
        print(line)




.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    writeControl    adjustable;

    writeInterval   0.1;

    purgeWrite      0;

    writeFormat     ascii;

    writePrecision  6;

    writeCompression off;

    timeFormat      general;

    timePrecision   6;

    runTimeModifiable true;


    // ************************************************************************* //





.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 0.078 seconds)


.. _sphx_glr_download_auto_tutorials_example_01_dictionaries.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: example_01_dictionaries.ipynb <example_01_dictionaries.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: example_01_dictionaries.py <example_01_dictionaries.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: example_01_dictionaries.zip <example_01_dictionaries.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_