.. _sect_penalty_file: 

Penalty File (.penalty)
-----------------------
The penalty file is only needed for inversion and contains the 
:Ref:`sect_penalty_matrix` penalty matrix used to regularize (aka stabilize)
the non-linear inversion of the EM data. This file is automatically 
generated by ``Mamba2D.m`` and here is documented for completeness. 

.. Note ::
    In a future update, the  penalty file will be removed
    as the penalty matrix can  be coded to be directly computed within MARE2DEM  
    in the same way as done in MARE3DEM.
    
The penalty matrix  is  :math:`{p \times q}`   penalty matrix
:math:`{\mathbf{R}}`, where *p* is the number of penalty rows and *q* is
the number of model parameters, that is applied to the model vector with
the matrix-vector product :math:`{\mathbf{R}} \mathbf{m}` ,as described
in :Ref:`sect_nonlinear_inversion`.  The file uses this format: 

.. code-block:: none

    Format: CSR_penalty_1.0
    <# non-zeros> <p>  
    # non-zeros  following lines: <column_index> <value>  
    p following lines: <row_pointer>
    last line: <# non-zeros+1>
 
This is the usual `compressed-sparse row (CSR) format
<https://en.wikipedia.org/wiki/Sparse_matrix#Compressed_sparse_row_(CSR,
_CRS_or_Yale_format)>`_ where

.. code-block:: none 

    k = row_pointer(i):row_pointer(i+1)-1
    j = column_index(k)
    R(i,j) = value(k)
 

The *value* parameters are used to store weights applied to the
penalties, but the specific values depend on the structure of the matrix
and the kind of penalty being applied.  For example, a second difference
penalty can be applied  for parameter *i* by setting, for a given row,
the value in the *i*\ th column to -1 and then using the value *1/n* for
the columns of all *n* surrounding model parameters, thereby making that
row's contribution to the penalty be the difference of the *i*\ th
parameter from the average of all its neighbors (which is equivalent to
the numerical 2nd difference).