.. _options:

====================================
Setting Kspace Options
====================================

``Py4mulas`` performs numpy operations, mainly products between kernels (see. :ref:`advanced`).
Therefore, it is important to optimize such operations. For this end a ``Py4mulas`` formula accepts the 
argument ``kspace_options``, which is a dictionary where one can specify three variabls:
``precomp``, ``chunk_size`` and ``memmap``.

.. code-block:: python

    from py4mulas.formulas import KuboFormula
    kspace_options = dict(precomp=True, chunk_size=10000, memmap=True)
    formula = KuboFormula(some_model, kspace_options=kspace_options, mu_kernel=some_mu_kernel, opera_kernel=some_opera_kernel)

Chunking the computation by setting  ``chunk_size``
===================================================

To accelerate the computation of any formula, one would perform matrix multiplication per momentum chunks.
This should drastically reduce the memory load during operations. Setting ``chunk_size=10000`` only an array
of size ``(10000, n, n)`` would be processed at once. Where ``n`` is the number of orbitals of the model's hamiltonian. 

Precomputing opera kernels by setting ``precomp``
=================================================

The parameter ``precomp`` enables the storage of the opera_kernel and eigen-energy arrays, 
preventing them from being recomputed when parameters such as (:math:`\mu`, :math:`T`, :math:`\eta`) 
are varied. 
Note that if Hamiltonian parameters are varied instead, this strategy will not accelerate 
the computation anymore. In such cases, we recommend computing the response in parallel using 
the :class:`~py4mulas.mpi.computers.HamParamComputer` class to improve speed. 
Conversely, when varying only (:math:`\mu`, :math:`T`, :math:`\eta`) variables, 
the precomputation strategy is often sufficient. 
However, it can also be combined with parallelization via the 
:class:`~py4mulas.mpi.computers.MuTEtaComputer` computer. 
While the precomputation strategy drastically accelerates the computation of the underlying 
responses, it can become a memory bottleneck if the stored arrays are huge. 
In this scenario, one can store the arrays on disc instead (see below).

Writting large arays to the disc by setting ``memmap``
======================================================

If this parameter is set to ``True``, the large arays are written into files using ``np.memmap``. This makes it
possible to handle large arrays when precomputing is to be performed. In the absence of precomputing this is likely
to not be relevent. In this case one can still dispatch the computation by setting ``chunk_size`` as discussed above.