Operators
==========

Arguments:

  * list of names of operators (json object) to compute during the simulation. Options are:
  
      * `"Hamiltonian"` (string) - Intensive Hamiltonian. Both real and imaginary component are output.
      * `"CellStress"` - Cell stress :math:`\tilde{\sigma}`  and cell tensor :math:`\pmb{h}` (see :ref:`Variable Cell`)

      * `"ChemicalPotential"` 

           * `"incl_ideal_gas"` - include ideal gas contribution to chemical potential. Default: `True`.
           * `"incl_self"` - include self interaction contribution to chemical potential. Default: `False`.
           * `"split_by_term"` (bool) - split into separate terms :math:`\mu = \mu_logQ + \mu_{ideal} + \mu_{self}`. This can be useful for debugging. Default: `False`.

      * `"Pressure"` - 

           * `"calc_tensor"` (bool) - output full pressure tensor into P[] in Voigt ordering (Pxx, Pyy, Pzz, Pyz, Pxz, Pxy). Default: `False`.
           * `"incl_ideal_gas"` (bool) - include ideal gas contribution to pressure. Default: `True`.
           * `"incl_mean_field"` (bool) - only for DriverRPA. Default: `True`.
           * `"incl_fluct"` (bool) - only for DriverRPA. Default: `True`.
           * `"split_by_term"` (bool) - split Pressure into separate terms :math:`P = P_{ideal} + P_{chain} + P_{smear} + P_{charge}`. See Nb#5 p117 for each of these terms. This can be useful for debugging). Default: `False`.
           * `"units"` (string) - Units to output pressure in. Options: `beta_Rg3` (units of :math:`\beta P R_g^3`) or `beta_b3` (units of :math:`\beta P b^3`). Default: `beta_Rg3`.

      * `"PressureUVSensitive"` - (beta)
      * `"DensityMolecule"` - output density per molecule
      * `"DensitySpecies"` - output density per species
      * `"DensityModelCustom"` - output density of quanties customized to model of interest. For ModelEdwardsCharge this is the total and charge density.
      * `"SpeciesFields"` - output species fields.

  * Each operator needs to specify the following parameters
    
      * `"averaging_type"` (string) - Specify how this operator should be averaged throughout the simulation. Options are 

          * `"none"` - do not perform any averaging
          * `"block"` - average the operator over a block of size specified by `block_size` in `Driver`. See :ref:`Block Averaging` section below.

      * `"save_history"` (bool) - Option to save history of operator to separate files. Always = true for scalar operators. Can be optionally set for field operators.

These operators are output to a file specified by :ref:`Output`.

Block Averaging
----------------
Block averaging (i.e. `block_size`) and the output frequency (i.e. `output_freq`) are handled independently within the code. Block averaging reports operators that are averaged over `block_size` sequential timesteps. The current value of operators are written to `operators.dat` and `op*.dat` files every `output_freq` steps. 

To see the expected results of block averaging, consider a timeseries of a given operator that takes the values d1 to d8 on 8 sequential timesteps t1 to d8:

.. table:: 

  ==========  ==== ==== ==== ====  ==== ==== ==== ====
  timestep     t1   t2   t3   t4    t5   t6   t7   t8
  ==========  ==== ==== ==== ====  ==== ==== ==== ====
  value        d1   d2   d3   d4    d5   d6   d7   d8
  ==========  ==== ==== ==== ====  ==== ==== ==== ====


If `block_size = 2` and `output_freq=1` then the output to `operators.dat` will be

.. table:: 

  ==========  ==== =========== ==== ===========  ==== =========== ==== ===========
  timestep     t1   t2          t3       t4       t5       t6      t7       t8
  ==========  ==== =========== ==== ===========  ==== =========== ==== ===========
  value        d1   (d1+d2)/2   d3   (d3+d4)/2    d5   (d5+d6)/2   d7   (d7+d8)/2
  ==========  ==== =========== ==== ===========  ==== =========== ==== ===========

If `block_size = 1` and `output_freq=2` then the output to `operators.dat` will be

.. table:: 

  ========== ==== ==== ==== ====
  timestep    t2   t4   t6   t8 
  ========== ==== ==== ==== ====
  value       d2   d4   d6   d8 
  ========== ==== ==== ==== ====


If `block_size = 2` and `output_freq=2` then the output to `operators.dat` will be

.. table::

  ==========   ===========  ===========  =========== ===========
  timestep      t2               t4           t6          t8
  ==========   ===========  ===========  =========== ===========
  value         (d1+d2)/2    (d3+d4)/2    (d5+d6)/2   (d7+d8)/2
  ==========   ===========  ===========  =========== ===========



Examples
----------------

Example (json) ::

  "operators" : {
    "Hamiltonian": {"averaging_type": "none"}, 
    "CellStress": {"averaging_type": "none"}
  },

Example (python) ::

  import openfts
  fts = openfts.OpenFTS()
  ...
  fts.add_operator(averaging_type='none',type='Hamiltonian')
  fts.add_operator(averaging_type='none',type='CellStress')
  ...