Setting up a simulation
==========================

A OpenFTS simulation requires many parameters to specify the simulation. Probably the best way to construct 
an input file is to look at the examples in `examples/`. Below is a brief description of the elements in an 
input file as well as links to more detailed sections of the documentation.

Another useful place to look is the :ref:`Python Module API`.

* **Cell** : holds information about the simulation cell (i.e. cell tensor, etc). See :ref:`Cell`.
  
* **Field Layout** : holds information common to all fields in the simulation box. This includes the
  number of plane waves in each dimension a reference to `Cell` object, precomputed coefficients
  (i.e. k2map) which only depend on the cell, and lots of utility functions for accessing elements
  within fields. See :ref:`Field Layout`.

* **Species**: holds information about the different species (i.e. atom/bead types). For a simple block polymer melt, 
  this might just be that statistical segement length, :math:`b_A` or :math:`b_B`, of each block. It could also be 
  the charge or smearing range of that species. See :ref:`Species`.

* **Model**: this class holds any information related to the Hamiltonian `H` of a field theory. This
  includes the definition of `H`, the list of fields that `H` is a functional of (e.g.
  :math:`\mu_+`, :math:`\mu_-`), the forces required to update `H` (e.g. :math:`\frac{\delta H}{\delta
  \mu_+}`, :math:`\frac{\delta H}{\delta \mu_-}`). Options of possible models are:

    * :ref:`Model Melt Chi AB`
    * :ref:`Model Melt Chi Multi-Species`
    * :ref:`Model Edwards`
    * :ref:`Model Edwards AB` (beta)
    * :ref:`Model Edwards Charge` (beta)

* **Molecules**: this is a list of each molecule in the system. This class holds information
  necessary to compute the :math:`\frac{\tilde{V} \phi_p}{\alpha_p} \ln Q_p` term that appears in
  the expression for `H`. If the molecule is a polymer, then the calculation of :math:`Q_p` requires
  the solution of a propagator :math:`q(r,s)`, and this is also handled by the **Chain** class.
  The **Chain** class also stores :math:`q(r,s)q^\dagger(r,s)` which is used to compute the density and
  stress operators. `Molecules` can be built up from a variety of `Chain` objects to create stars, bottlebrushes
  or simple linear chains. Options of possible molecules are:

    * :ref:`Molecule Polymer Linear (continuous)`
    * :ref:`Molecule Polymer Linear (discrete)`
    * :ref:`Molecule Polymer Comb` (continuous or discrete)

* **Operators**: this class holds a list of operators to compute in the system. See :ref:`Operators`.

* **Output**: this class handles the output to files during the simulation. See :ref:`Output`.

* **Driver**: holds information related to the main `for-loop` in the code. This includes what
  actual simulation will be performed (e.g. SCFT or CL) and all of the relevant parameters necessary
  to run such a simulation (e.g. how many steps a simulation will run, how the `model` fields will be
  updated, what quantities will be output during the simulation, and how frequently this output fill
  be, etc). The `Driver` class is where the `Run()` method is contained. Options of possible drivers are:

    * :ref:`Driver SCFTCL`
    * Driver :ref:`Particle Map`
    * :ref:`Driver RPA` (beta)
    
  * **Field Updater**: the `Driver` class contains a `FieldUpdater` class that handles the algorithm 
    for updating the :math:`\mu` fields. For a semi-implicit `FieldUpdater` (e.g. SIS, ETD), the 
    `FieldUpdater` extracts a `linear_response_kernel` :math:`\hat{\kappa}(\pmb{k})` from the `Model` 
    class, which in turn calculate the Debye functions :math:`\hat{g}_D` for each `Molecule` in the 
    system. Thus, to add a new `FieldUpdater` or to extend an existing one, edits are required in the 
    `FieldUpdater`, `Model` and `Molecule` derived classes. Options of possible field updaters are 

    * :ref:`Field Updater EMPEC`
    * :ref:`Field Updater SIS`
    * :ref:`Field Updater Euler`

Many of these classes provide an interface that derived classes must implement and OpenFTS is
structured with the expectation that new functionality will be added to the code by adding new
classes that derive from one of these `Base` classes.