oasislmf.pytools.gulmc.structure
================================

.. py:module:: oasislmf.pytools.gulmc.structure

.. autoapi-nested-parse::

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

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



Attributes
----------

.. autoapisummary::

   oasislmf.pytools.gulmc.structure.logger
   oasislmf.pytools.gulmc.structure.STRUCTURE_DIR
   oasislmf.pytools.gulmc.structure.ARRAY_FILES


Functions
---------

.. autoapisummary::

   oasislmf.pytools.gulmc.structure.gulmc_structure_exists
   oasislmf.pytools.gulmc.structure.build_structures
   oasislmf.pytools.gulmc.structure.create_gulmc_structure
   oasislmf.pytools.gulmc.structure.load_gulmc_structure


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

.. py:data:: logger

.. py:data:: STRUCTURE_DIR
   :value: 'gulmc_structure'


.. py:data:: ARRAY_FILES
   :value: ['items', 'coverages', 'item_map_ja_areaperil_ids', 'item_map_ja_offsets',...


.. py:function:: gulmc_structure_exists(run_dir)

   Check whether pre-computed gulmc structures exist.


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

   Build all read-only gulmc 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_gulmc_structure``) rather than repeated in every parallel
   gulmc 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).
       dynamic_footprint (bool): whether to apply dynamic footprint logic.
       model_df_engine (str): engine for loading model dataframes.

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


.. py:function:: create_gulmc_structure(run_dir, ignore_file_type, peril_filter, dynamic_footprint, model_df_engine)

   Build and save all read-only gulmc 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).
       dynamic_footprint (bool): whether to apply dynamic footprint logic.
       model_df_engine (str): engine for loading model dataframes.


.. py:function:: load_gulmc_structure(run_dir)

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

   Each array is loaded with ``mmap_mode='r'`` so that multiple gulmc
   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.