oasislmf.pytools.gul.structure
==============================

.. py:module:: oasislmf.pytools.gul.structure

.. autoapi-nested-parse::

   Pre-compute and persist gulpy read-only data structures.

   Follows the same pattern as ``oasislmf.pytools.gulmc.structure``:
     - ``create_gulpy_structure`` builds all read-only numpy arrays once and
       saves them as ``.npy`` files.
     - ``load_gulpy_structure`` memory-maps them via ``np.load(mmap_mode='r')``,
       allowing multiple gulpy processes to share physical memory pages through
       the OS page cache.



Attributes
----------

.. autoapisummary::

   oasislmf.pytools.gul.structure.logger
   oasislmf.pytools.gul.structure.STRUCTURE_DIR
   oasislmf.pytools.gul.structure.ARRAY_FILES


Functions
---------

.. autoapisummary::

   oasislmf.pytools.gul.structure.gulpy_structure_exists
   oasislmf.pytools.gul.structure.build_structures
   oasislmf.pytools.gul.structure.create_gulpy_structure
   oasislmf.pytools.gul.structure.load_gulpy_structure


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

.. py:data:: logger

.. py:data:: STRUCTURE_DIR
   :value: 'gulpy_structure'


.. py:data:: ARRAY_FILES
   :value: ['damage_bins', 'coverages', 'items', 'item_map_hm', 'item_map_hm_keys', 'item_map_ja_offsets',...


.. py:function:: gulpy_structure_exists(run_dir)

   Check whether pre-computed gulpy structures exist.


.. py:function:: build_structures(run_dir, ignore_file_type, peril_filter)

   Build all read-only gulpy data structures from input files.

   This extracts the preparation logic from ``manager.run()`` into a
   standalone callable so that it can be invoked once (by
   ``create_gulpy_structure``) rather than repeated in every parallel
   gulpy process.

   Args:
       run_dir (str): path to the run directory.
       ignore_file_type (set[str]): file extensions to ignore when loading.
       peril_filter (list): list of perils to include (empty = all).

   Returns:
       dict: mapping variable names to numpy arrays / scalars.


.. py:function:: create_gulpy_structure(run_dir, ignore_file_type, peril_filter)

   Build and save all read-only gulpy data structures as ``.npy`` files.

   Args:
       run_dir (str): path to the run directory.
       ignore_file_type (set[str]): file extensions to ignore when loading.
       peril_filter (list): list of perils to include (empty = all).


.. py:function:: load_gulpy_structure(run_dir)

   Load pre-computed gulpy structures via memory-mapped numpy files.

   Each array is loaded with ``mmap_mode='r'`` so that multiple gulpy
   processes share physical memory pages through the OS page cache.

   Args:
       run_dir (str): path to the run directory.

   Returns:
       dict: mapping variable names to numpy arrays / scalars.