:py:mod:`FELiCS.IO.Writer`
==========================

.. py:module:: FELiCS.IO.Writer


Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   FELiCS.IO.Writer.Writer




Attributes
~~~~~~~~~~

.. autoapisummary::

   FELiCS.IO.Writer.logger


.. py:data:: logger

   

.. py:class:: Writer(mesh=None, exportDir='Output')


   Utility class for exporting FELiCS fields and meshes to HDF5/XDMF.

   A writer instance is associated with a mesh and an export directory.
   When initialized with a mesh, the mesh is immediately exported to
   ``mesh.h5`` in the target directory. If no mesh is given at
   initialization, the mesh from the first exported field is used and
   written when data is exported.

   Multiple HDF5/XDMF files can be created within the same export
   directory. All fields written by a single writer are assumed to be
   defined on the same mesh.

   **Initialize the Writer object**

   :param mesh: Mesh associated with this writer. If provided, the mesh is exported
                immediately to ``mesh.h5`` in the export directory.
   :type mesh: :py:class:`FELiCSMesh` or :py:obj:`None`, *optional*
   :param exportDir: Directory where all HDF5/XDMF output files and the mesh file are
                     written. The directory is created if it does not exist.
   :type exportDir: :py:class:`str`, *optional*

   :ivar mesh: Mesh associated with the writer. If initially ``None``, it is set
               from the first field passed to an export method.
   :vartype mesh: :py:class:`FELiCSMesh` or :py:obj:`None`
   :ivar exportFolder: Path to the directory used for all exported files.
   :vartype exportFolder: :py:class:`str`
   :ivar meshFileName: Path to the exported mesh HDF5 file, typically
                       ``<exportFolder>/mesh.h5``.
   :vartype meshFileName: :py:class:`str`
   :ivar exportMesh: Mesh object used specifically for export, usually
                     ``mesh.exportMesh`` of the associated FELiCS mesh.
   :vartype exportMesh: :py:class:`object`
   :ivar exportSpace: Finite element function space associated with the export mesh, used
                      to represent exported scalar fields.
   :vartype exportSpace: :py:class:`dolfinx.fem.FunctionSpace`
   :ivar mappingP2ToExport: Mapping from P2 degrees of freedom of a source space to the export
                            space. Created on demand during the first P2 export.

   :vartype mappingP2ToExport: :py:class:`ndarray`, *optional*

   .. admonition:: Notes

      All fields exported by a given writer are assumed to be compatible with
      the same mesh. If fields are defined on different meshes, a separate
      :class:`Writer` instance with a different export directory must be used
      for each mesh; otherwise the generated XMF files will not be readable
      correctly.

   .. py:method:: exportListOfFieldsToH5(listOfFields, fileName, attributes=None)

      Export a list of fields to a single HDF5 file and generate XMF content.

      Each field in the list may be scalar, vector, or mixed. Internally,
      the fields are decomposed into scalar subfields, mapped or
      interpolated to the export space, written to `<fileName>.h5`, and
      referenced in an associated XMF file `<fileName>.xmf`.

      :param listOfFields: List of `Field` (or subclasses) to be written to a single HDF5
                           file.
      :type listOfFields: :py:class:`list` of :py:class:`Field`
      :param fileName: Base name of the HDF5/XMF files. The export directory is
                       automatically prefixed. If the name ends with ``.h5``, the
                       suffix is stripped before adding the correct extensions.
      :type fileName: :py:class:`str`
      :param attributes: Additional attributes to store as datasets in the HDF5 file. Each
                         element is expected to provide ``name`` and ``value`` attributes.
      :type attributes: :py:class:`list` of :py:class:`objects`, *optional*

      :returns: XMF header/body text corresponding to the exported fields but
                without the final XMF footer. This can be reused to append
                additional attributes before closing the XMF document.
      :rtype: :py:class:`str`


   .. py:method:: exportFieldToH5(field, fileName, attributes=None)

      Export a single field to an HDF5 file and generate XMF content.

      The field may be scalar, vector, or mixed. It is internally
      decomposed into scalar subfields, mapped or interpolated to the
      export space, written to `<fileName>.h5`, and referenced in an
      associated XMF file `<fileName>.xmf`.

      :param field: Field (or subclass) to be written to an HDF5 file.
      :type field: :py:class:`Field`
      :param fileName: Base name of the HDF5/XMF files. The export directory is
                       automatically prefixed. If the name ends with ``.h5``, the
                       suffix is stripped before adding the correct extensions.
      :type fileName: :py:class:`str`
      :param attributes: Additional attributes to store as datasets in the HDF5 file. Each
                         element is expected to provide ``name`` and ``value`` attributes.
      :type attributes: :py:class:`list` of :py:class:`objects`, *optional*

      :returns: XMF header/body text corresponding to the exported field but
                without the final XMF footer.
      :rtype: :py:class:`str`