.. _build_cluster..

******************************
Automated cluster construction
******************************

Included in ChemShell is a workflow for the automated construction and
and partitioning of clusters to model the solid-state. These routines
require only the provision of a relaxed periodic structure and some
known parameters to reproducibly build effectively partitioned clusters
for further QM/MM studies.

The workflow builds on and extends ChemShell's :ref:`cluster cutting tools <cutting_clusters>`.

Main features
=============

* Construction and partitioning of clusters from periodic input in one function call.
* Multiple schemes for selecting cluster QM regions (radial, `unit cell <https://pubs.aip.org/aip/jcp/article/151/18/184114/198016/Towards-a-transferable-design-of-solid-state1>`_ , `SKZCAM <https://pubs.aip.org/aip/jcp/article/156/12/124704/2841115/General-embedded-cluster-protocol-for-accurate>`_).
* Defaults to produce a sensible cluster with minimal user input, reducing barrier to entry.
* Options for experienced users to construct highly specific clusters.

Input parameters
================

All parameters should be declared as a dictionary and provided to the workflow
though the ``setup`` function. Below is an exhaustive list of options and their
default settings.

General parameters
------------------

.. py:attribute:: input

    (Default: ``''``) Filename of input periodic structure.

.. py:attribute:: input_qm

    (Default: ``''``) Filename of user specified QM region.

.. py:attribute:: output_prefix

    (Default: ``'Partitioned_Cluster'``) Output filename.

.. py:attribute:: partition_mode

    (Default: ``'radial'``) The method of partitioning the cluster. Options are 'radial', 'unit_cell' or 'skzcam'

.. py:attribute:: radius_cluster

    (Default: ``40.0``) Radius of the cluster produced (in bohr).

.. py:attribute:: active_radius

    (Default: ``20.0``) Active radius within this cluster - regions 1, 2 and 3.

.. py:attribute:: charges

    (Default: ``{}``) A dictionary specifying the charges on each ion.

.. py:attribute:: shell_species

    (Default: ``''``) Species to apply shells to (core-shell model).

.. py:attribute:: shell_charge

    (Default: ``None``) Charge of the shell specified by ``shell_atom``.

.. py:attribute:: adjust_charge

    (Default: ``'coordination_scaled'``) Method by which the charges are adjusted to mimic the extended bulk.

.. py:attribute:: bq_margin

    (Default: ``10``) The separation of the point charges from the surface of the cluster.

.. py:attribute:: bq_density

    (Default: ``5``) Point charge density in the space surround the cluster.

.. py:attribute:: qmmm_interface

    (Default: ``'explicit'``) Methodology of interfacing QM with MM.

.. py:attribute:: interface_exclude

    (Default: ``''``) Species to exclude from the interface region.

.. py:attribute:: cutoff_boundary

    (Default: ``4.0``) Distance from region 1 the defines size of region 2.

.. py:attribute:: origin_bulk

    (Default: ``None``) Origin of the periodic fragment in fractional coords. None implies centring at (0,0,0)

.. py:attribute:: print_warnings

    (Default: ``True``) Prints warnings about defaults used and best practice.

QM region partitioning options
------------------------------

.. py:attribute:: radius

    (Default: ``5``) QM region radius. 'radial' partitioning only.

.. py:attribute:: origin_qm

    (Default: ``None``) Origin of the QM fragment in fractional coords. None implies centring at (0,0,0)

.. py:attribute:: check_qm_region

    (Default: ``True``) Check if the qm region is the same size as the input fragment. 'unit_cell' partitioning only.

.. py:attribute:: tol

    (Default: ``0.003``) Tolerance on how close an atom must be tobe included in the QM region. 'unit_cell' partitioning only.

.. py:attribute:: skzcam_cation

    (Default: ``''``) Cation for RDF in SKZCAM partitioning.

.. py:attribute:: skzcam_shells

    (Default: ``1``) Number of RDF shells to be selected in SKZCAM partitioning. Counts from zero.

.. py:attribute:: skzcam_anion_tol

    (Default: ``0.05``) Tolerance of selecting anions to be included in SKZCAM QM region.


Workflow functions
==================

The ``ClusterCutting`` class contains the following method that runs the automated workflow.

.. py:method:: run()

    This function runs the automated cluster construction to build a model.