bluemira.materials.cache
========================

.. py:module:: bluemira.materials.cache

.. autoapi-nested-parse::

   Classes and methods to load, store, and retrieve materials.



Attributes
----------

.. autoapisummary::

   bluemira.materials.cache.vacuum_void


Classes
-------

.. autoapisummary::

   bluemira.materials.cache.MaterialCache


Functions
---------

.. autoapisummary::

   bluemira.materials.cache.establish_material_cache
   bluemira.materials.cache.get_cached_material


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

.. py:data:: vacuum_void

.. py:class:: MaterialCache

   A helper class for loading and caching materials.

   .. rubric:: Notes

   Extend the `available_classes` attribute to load custom classes.


   .. py:attribute:: _instance
      :type:  MaterialCache | None
      :value: None



   .. py:method:: get_instance() -> MaterialCache
      :classmethod:


      Get the singleton instance of the MaterialCache.

      :returns: The singleton instance of the MaterialCache.
      :rtype: MaterialCache



   .. py:method:: __getattr__(value: str)

      Allow attribute access to cached materials

      :returns: The requested Material

      :raises AttributeError: No attribute found



   .. py:method:: load_from_package(package)

      Load material package



   .. py:method:: _get_material(name)


   .. py:method:: get_material(name: str, *, clone: bool = True)

      Get the named material from the material dictionary

      :param name: The name of the material to retrieve from the dictionary
      :param clone: If True, get a clone (deepcopy) of the material, else get the actual material
                    as stored in the material dictionary. By default True.

      :rtype: The requested material.



.. py:function:: establish_material_cache(materials_package: str | object)

   Load the material data from the provided json files into the global material cache
   instance.

   This instance can be accessed using the `MaterialCache.get_instance()`
   function.

   :param materials_package: A list of paths to the data files to load into the material cache.

   :rtype: The material cache.


.. py:function:: get_cached_material(material_name: str, cache: MaterialCache | None = None) -> matproplib.material.Material | None

   Get the named material from the MaterialCache.

   If cache is None, the global cache instance is used.

   :param material_name: The name of the material to retrieve from the dictionary
   :param cache: The material cache to retrieve the material from. By default the global cache.

   :returns: The requested material.

   :raises MaterialsError: If the material name is not a string.