tutorials/23-generate-configuration-lists.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Generate, manipulate and restrict (lists of) configurations"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "using JAC"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "Many atomic computations are built upon the term of a configuration or lists (respective arrays) of such configurations. These list of configuration must generated prior to the computations and, more often than not, should obey certain restrictions, concerning for instance their parity or the occupation of certain shells. -- While such lists can always be specified individually, here we show how to generate them from a set of *reference configurations* and by applying (a set of) *restrictions*. This automatic generation of configuration lists is particular helpful if electron capture, dielectronic recombination or cascades processes are to be studied. However, they also help support systematic enlargements of wave functions.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let us start with showing the internal use and representation of a configuration:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "search: \u001b[0m\u001b[1mC\u001b[22m\u001b[0m\u001b[1mo\u001b[22m\u001b[0m\u001b[1mn\u001b[22m\u001b[0m\u001b[1mf\u001b[22m\u001b[0m\u001b[1mi\u001b[22m\u001b[0m\u001b[1mg\u001b[22m\u001b[0m\u001b[1mu\u001b[22m\u001b[0m\u001b[1mr\u001b[22m\u001b[0m\u001b[1ma\u001b[22m\u001b[0m\u001b[1mt\u001b[22m\u001b[0m\u001b[1mi\u001b[22m\u001b[0m\u001b[1mo\u001b[22m\u001b[0m\u001b[1mn\u001b[22m \u001b[0m\u001b[1mC\u001b[22m\u001b[0m\u001b[1mo\u001b[22m\u001b[0m\u001b[1mn\u001b[22m\u001b[0m\u001b[1mf\u001b[22m\u001b[0m\u001b[1mi\u001b[22m\u001b[0m\u001b[1mg\u001b[22m\u001b[0m\u001b[1mu\u001b[22m\u001b[0m\u001b[1mr\u001b[22m\u001b[0m\u001b[1ma\u001b[22m\u001b[0m\u001b[1mt\u001b[22m\u001b[0m\u001b[1mi\u001b[22m\u001b[0m\u001b[1mo\u001b[22m\u001b[0m\u001b[1mn\u001b[22mR Abstra\u001b[0m\u001b[1mc\u001b[22mtC\u001b[0m\u001b[1mo\u001b[22m\u001b[0m\u001b[1mn\u001b[22m\u001b[0m\u001b[1mf\u001b[22m\u001b[0m\u001b[1mi\u001b[22m\u001b[0m\u001b[1mg\u001b[22m\u001b[0m\u001b[1mu\u001b[22m\u001b[0m\u001b[1mr\u001b[22m\u001b[0m\u001b[1ma\u001b[22m\u001b[0m\u001b[1mt\u001b[22m\u001b[0m\u001b[1mi\u001b[22m\u001b[0m\u001b[1mo\u001b[22m\u001b[0m\u001b[1mn\u001b[22mRestriction\n",
      "\n"
     ]
    },
    {
     "data": {
      "text/latex": [
       "\\texttt{struct  ManyElectron.Configuration}       ... defines a struct for a non-relativistic electron configuration that is fully speficied by its shell notations          (such as \"1s\", \"2s\", \"2p\", ....) and the corresponding occupation numbers (>= 0). An electron configuration          is independent of any order of the shells, and a zero occupation is assumed for all shells that do not appear as a          key in the shell (dictionary). Therefore, the number of keys do not allow any conclusion about the underlying orbital          space of any considered computation that include more than just a single configuration.\n",
       "\n",
       "\\begin{verbatim}\n",
       "+ shells         ::Dict{Shell,Int64}   ... Dictionary that maps shells to their occupation.\n",
       "+ NoElectrons    ::Int64               ... No. of electrons.\n",
       "\\end{verbatim}\n",
       "\\rule{\\textwidth}{1pt}\n",
       "\\texttt{ManyElectron.Configuration(sa::String)}       ... constructor for a given configuration string, such as \"[He]\", \"[Ne]\", \"[Ne] 3s 3p\\^{}6\"  or \"1s 2p\\^{}6 3s\\^{}2 3p\".\n",
       "\n"
      ],
      "text/markdown": [
       "`struct  ManyElectron.Configuration`       ... defines a struct for a non-relativistic electron configuration that is fully speficied by its shell notations          (such as \"1s\", \"2s\", \"2p\", ....) and the corresponding occupation numbers (>= 0). An electron configuration          is independent of any order of the shells, and a zero occupation is assumed for all shells that do not appear as a          key in the shell (dictionary). Therefore, the number of keys do not allow any conclusion about the underlying orbital          space of any considered computation that include more than just a single configuration.\n",
       "\n",
       "```\n",
       "+ shells         ::Dict{Shell,Int64}   ... Dictionary that maps shells to their occupation.\n",
       "+ NoElectrons    ::Int64               ... No. of electrons.\n",
       "```\n",
       "\n",
       "---\n",
       "\n",
       "`ManyElectron.Configuration(sa::String)`       ... constructor for a given configuration string, such as \"[He]\", \"[Ne]\", \"[Ne] 3s 3p^6\"  or \"1s 2p^6 3s^2 3p\".\n"
      ],
      "text/plain": [
       "  \u001b[36mstruct  ManyElectron.Configuration\u001b[39m ... defines a struct for a\n",
       "  non-relativistic electron configuration that is fully speficied by its shell\n",
       "  notations (such as \"1s\", \"2s\", \"2p\", ....) and the corresponding occupation\n",
       "  numbers (>= 0). An electron configuration is independent of any order of the\n",
       "  shells, and a zero occupation is assumed for all shells that do not appear\n",
       "  as a key in the shell (dictionary). Therefore, the number of keys do not\n",
       "  allow any conclusion about the underlying orbital space of any considered\n",
       "  computation that include more than just a single configuration.\n",
       "\n",
       "\u001b[36m  + shells         ::Dict{Shell,Int64}   ... Dictionary that maps shells to their occupation.\u001b[39m\n",
       "\u001b[36m  + NoElectrons    ::Int64               ... No. of electrons.\u001b[39m\n",
       "\n",
       "  ────────────────────────────────────────────────────────────────────────────\n",
       "\n",
       "  \u001b[36mManyElectron.Configuration(sa::String)\u001b[39m ... constructor for a given\n",
       "  configuration string, such as \"[He]\", \"[Ne]\", \"[Ne] 3s 3p^6\" or \"1s 2p^6\n",
       "  3s^2 3p\"."
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "? Configuration"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This enables us to define the ground-configuration of chlorine-like ions by simply typing:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Configuration: 1s^2 2s^2 2p^6 3s^2 3p^5 "
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "config = Configuration(\"[Ne] 3s^2 3p^5\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "and which we shall use as *reference configuration* to generate lists of excited configurations:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1-element Array{Configuration,1}:\n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^5 "
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "refConfigs = [config]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To generate such lists, we can use the function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/latex": [
       "\\texttt{Basics.generateConfigurations(refConfigs::Array\\{Configuration,1\\}, fromShells::Array\\{Shell,1\\}, toShells::Array\\{Shell,1\\})}       ... generates all nonrelativistic configurations due to the (single) excitation of an electron fromShells –> toShells         for all given reference configurations. A confList::Array\\{Configuration,1\\} is returned.\n",
       "\n",
       "\\rule{\\textwidth}{1pt}\n",
       "\\texttt{Basics.generateConfigurations(refConfigs::Array\\{Configuration,1\\}, fromShells::Array\\{Shell,1\\}, toShells::Array\\{Shell,1\\},                                 noex::Int64; restrictions::Array\\{AbstractConfigurationRestriction,1\\}=AbstractConfigurationRestriction[])}       ... generates all nonrelativistic configurations with excitation of up to noex electrons fromShells –> toShells         for all given reference configurations. Moreover, the list of restrictions (if any is given) is finally applied          to restrict the configurations to a given set of limitations. It remains the reponsibility of the user to make sure that         the given restrictions do not contradict each other and are consistent with what is to be achieved. The given set of          restrictions can be easily extended if this need arises by the users. A confList::Array\\{Configuration,1\\} is returned.\n",
       "\n"
      ],
      "text/markdown": [
       "`Basics.generateConfigurations(refConfigs::Array{Configuration,1}, fromShells::Array{Shell,1}, toShells::Array{Shell,1})`       ... generates all nonrelativistic configurations due to the (single) excitation of an electron fromShells –> toShells         for all given reference configurations. A confList::Array{Configuration,1} is returned.\n",
       "\n",
       "---\n",
       "\n",
       "`Basics.generateConfigurations(refConfigs::Array{Configuration,1}, fromShells::Array{Shell,1}, toShells::Array{Shell,1},                                 noex::Int64; restrictions::Array{AbstractConfigurationRestriction,1}=AbstractConfigurationRestriction[])`       ... generates all nonrelativistic configurations with excitation of up to noex electrons fromShells –> toShells         for all given reference configurations. Moreover, the list of restrictions (if any is given) is finally applied          to restrict the configurations to a given set of limitations. It remains the reponsibility of the user to make sure that         the given restrictions do not contradict each other and are consistent with what is to be achieved. The given set of          restrictions can be easily extended if this need arises by the users. A confList::Array{Configuration,1} is returned.\n"
      ],
      "text/plain": [
       "  \u001b[36mBasics.generateConfigurations(refConfigs::Array{Configuration,1},\n",
       "  fromShells::Array{Shell,1}, toShells::Array{Shell,1})\u001b[39m ... generates all\n",
       "  nonrelativistic configurations due to the (single) excitation of an electron\n",
       "  fromShells –> toShells for all given reference configurations. A\n",
       "  confList::Array{Configuration,1} is returned.\n",
       "\n",
       "  ────────────────────────────────────────────────────────────────────────────\n",
       "\n",
       "  \u001b[36mBasics.generateConfigurations(refConfigs::Array{Configuration,1},\n",
       "  fromShells::Array{Shell,1}, toShells::Array{Shell,1},                       \n",
       "           noex::Int64;\n",
       "  restrictions::Array{AbstractConfigurationRestriction,1}=AbstractConfigurationRestriction[])\u001b[39m\n",
       "  ... generates all nonrelativistic configurations with excitation of up to\n",
       "  noex electrons fromShells –> toShells for all given reference\n",
       "  configurations. Moreover, the list of restrictions (if any is given) is\n",
       "  finally applied to restrict the configurations to a given set of\n",
       "  limitations. It remains the reponsibility of the user to make sure that the\n",
       "  given restrictions do not contradict each other and are consistent with what\n",
       "  is to be achieved. The given set of restrictions can be easily extended if\n",
       "  this need arises by the users. A confList::Array{Configuration,1} is\n",
       "  returned."
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "? Basics.generateConfigurations"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "which automatically generates configurations by -- single or multiple -- replacements of electrons from given shells (`fromShells`) to the same or other shells (`toShells`). We first wish, for instance, to account for all single excitations from the $3s$ and $3p$ into the $3d,\\; 4s,\\; 4p,\\; 4d,\\; 4f$ shells."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "7-element Array{Shell,1}:\n",
       " 3s\n",
       " 3p\n",
       " 3d\n",
       " 4s\n",
       " 4p\n",
       " 4d\n",
       " 4f"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "fromShells = [Shell(\"3s\"), Shell(\"3p\")]\n",
    "toShells   = [Shell(\"3s\"), Shell(\"3p\"), Shell(\"3d\"), Shell(\"4s\"), Shell(\"4p\"), Shell(\"4d\"), Shell(\"4f\")]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "12-element Array{Configuration,1}:\n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^5      \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^1 3p^6      \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^1 3p^5 3d^1 \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^1 3p^5 4s^1 \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^1 3p^5 4p^1 \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^1 3p^5 4d^1 \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^1 3p^5 4f^1 \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^4 3d^1 \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^4 4s^1 \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^4 4p^1 \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^4 4d^1 \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^4 4f^1 "
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "Basics.generateConfigurations(refConfigs, fromShells, toShells)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As seen from this list, the reference configuration(s) are also part of the generated list since such lists are often used as *starting point* to generate lists with a larger number of excitations. Apart from single excitations, i.e. the replacement of a single electron from the `fromShells` to the `toShells`, we can also request for double or multiple excitations by an additional argument `noex = 3` (triple excitations):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "164-element Array{Configuration,1}:\n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^5                \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^1 3p^6                \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^1 3p^5 3d^1           \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^1 3p^5 4s^1           \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^1 3p^5 4p^1           \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^1 3p^5 4d^1           \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^1 3p^5 4f^1           \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^4 3d^1           \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^4 4s^1           \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^4 4p^1           \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^4 4d^1           \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^4 4f^1           \n",
       " Configuration: 1s^2 2s^2 2p^6 3p^6 3d^1                \n",
       " ⋮                                                      \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^2 4s^1 4d^1 4f^1 \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^2 4s^1 4f^2      \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^2 4p^3           \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^2 4p^2 4d^1      \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^2 4p^2 4f^1      \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^2 4p^1 4d^2      \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^2 4p^1 4d^1 4f^1 \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^2 4p^1 4f^2      \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^2 4d^3           \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^2 4d^2 4f^1      \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^2 4d^1 4f^2      \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^2 4f^3           "
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "wa = Basics.generateConfigurations(refConfigs, fromShells, toShells, 3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Obviously, the number of configurations may increase very rapidly and further restrictions might be in order to keep configuration expansions feasible. Moreover, configurations of both parity are generated with such a quick *call* of this function by just making multiple replacements. To generate more *refined* lists of configurations, we can apply in addition one or several **restrictions** to the generated list. These restrictions are specified by an optional argument to the function `Basics.generateConfigurations` above and provided as list of type:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "search: \u001b[0m\u001b[1mA\u001b[22m\u001b[0m\u001b[1mb\u001b[22m\u001b[0m\u001b[1ms\u001b[22m\u001b[0m\u001b[1mt\u001b[22m\u001b[0m\u001b[1mr\u001b[22m\u001b[0m\u001b[1ma\u001b[22m\u001b[0m\u001b[1mc\u001b[22m\u001b[0m\u001b[1mt\u001b[22m\u001b[0m\u001b[1mC\u001b[22m\u001b[0m\u001b[1mo\u001b[22m\u001b[0m\u001b[1mn\u001b[22m\u001b[0m\u001b[1mf\u001b[22m\u001b[0m\u001b[1mi\u001b[22m\u001b[0m\u001b[1mg\u001b[22m\u001b[0m\u001b[1mu\u001b[22m\u001b[0m\u001b[1mr\u001b[22m\u001b[0m\u001b[1ma\u001b[22m\u001b[0m\u001b[1mt\u001b[22m\u001b[0m\u001b[1mi\u001b[22m\u001b[0m\u001b[1mo\u001b[22m\u001b[0m\u001b[1mn\u001b[22m\u001b[0m\u001b[1mR\u001b[22m\u001b[0m\u001b[1me\u001b[22m\u001b[0m\u001b[1ms\u001b[22m\u001b[0m\u001b[1mt\u001b[22m\u001b[0m\u001b[1mr\u001b[22m\u001b[0m\u001b[1mi\u001b[22m\u001b[0m\u001b[1mc\u001b[22m\u001b[0m\u001b[1mt\u001b[22m\u001b[0m\u001b[1mi\u001b[22m\u001b[0m\u001b[1mo\u001b[22m\u001b[0m\u001b[1mn\u001b[22m\n",
      "\n"
     ]
    },
    {
     "data": {
      "text/latex": [
       "\\texttt{abstract type ManyElectron.AbstractConfigurationRestriction}      ... defines an abstract types for dealing with restrictions that need to be applied to a list of configurations.         Typically, a loop through is made through all given restrictions and all configurations are tested to obey all         these restrictions. Two contradicting restrictions, for instance RestrictParity(plus) \\& RestrictParity(minus),         therefore leads zero configurations in all cases. It remains the reponsibility of the user to make sure that         the given restrictions are consistent with what is to be achieved. The given set of restrictions can be easily         extended if this need arises by the users.\n",
       "\n",
       "\\begin{verbatim}\n",
       "+ RestrictNoElectronsTo(..)    ... to restrict the total number of electron in high subshells.\n",
       "+ RestrictParity(..)           ... to restrict to configurations with a given parity.\n",
       "+ RestrictToShellDoubles(..)   ... to allow only double occupations in high subshells.\n",
       "+ RequestMinimumOccupation(..) ... to request a minimum occupation in a given set of shells.\n",
       "+ RequestMaximumOccupation(..) ... to request a maximum occupation in a given set of shells.\n",
       "\\end{verbatim}\n"
      ],
      "text/markdown": [
       "`abstract type ManyElectron.AbstractConfigurationRestriction`      ... defines an abstract types for dealing with restrictions that need to be applied to a list of configurations.         Typically, a loop through is made through all given restrictions and all configurations are tested to obey all         these restrictions. Two contradicting restrictions, for instance RestrictParity(plus) & RestrictParity(minus),         therefore leads zero configurations in all cases. It remains the reponsibility of the user to make sure that         the given restrictions are consistent with what is to be achieved. The given set of restrictions can be easily         extended if this need arises by the users.\n",
       "\n",
       "```\n",
       "+ RestrictNoElectronsTo(..)    ... to restrict the total number of electron in high subshells.\n",
       "+ RestrictParity(..)           ... to restrict to configurations with a given parity.\n",
       "+ RestrictToShellDoubles(..)   ... to allow only double occupations in high subshells.\n",
       "+ RequestMinimumOccupation(..) ... to request a minimum occupation in a given set of shells.\n",
       "+ RequestMaximumOccupation(..) ... to request a maximum occupation in a given set of shells.\n",
       "```\n"
      ],
      "text/plain": [
       "  \u001b[36mabstract type ManyElectron.AbstractConfigurationRestriction\u001b[39m ... defines an\n",
       "  abstract types for dealing with restrictions that need to be applied to a\n",
       "  list of configurations. Typically, a loop through is made through all given\n",
       "  restrictions and all configurations are tested to obey all these\n",
       "  restrictions. Two contradicting restrictions, for instance\n",
       "  RestrictParity(plus) & RestrictParity(minus), therefore leads zero\n",
       "  configurations in all cases. It remains the reponsibility of the user to\n",
       "  make sure that the given restrictions are consistent with what is to be\n",
       "  achieved. The given set of restrictions can be easily extended if this need\n",
       "  arises by the users.\n",
       "\n",
       "\u001b[36m  + RestrictNoElectronsTo(..)    ... to restrict the total number of electron in high subshells.\u001b[39m\n",
       "\u001b[36m  + RestrictParity(..)           ... to restrict to configurations with a given parity.\u001b[39m\n",
       "\u001b[36m  + RestrictToShellDoubles(..)   ... to allow only double occupations in high subshells.\u001b[39m\n",
       "\u001b[36m  + RequestMinimumOccupation(..) ... to request a minimum occupation in a given set of shells.\u001b[39m\n",
       "\u001b[36m  + RequestMaximumOccupation(..) ... to request a maximum occupation in a given set of shells.\u001b[39m"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "?AbstractConfigurationRestriction"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Each of these pre-defined restriction is based on its own data type and constructor to specify further details. The simplest restriction perhaps is:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "search: \u001b[0m\u001b[1mR\u001b[22m\u001b[0m\u001b[1me\u001b[22m\u001b[0m\u001b[1ms\u001b[22m\u001b[0m\u001b[1mt\u001b[22m\u001b[0m\u001b[1mr\u001b[22m\u001b[0m\u001b[1mi\u001b[22m\u001b[0m\u001b[1mc\u001b[22m\u001b[0m\u001b[1mt\u001b[22m\u001b[0m\u001b[1mP\u001b[22m\u001b[0m\u001b[1ma\u001b[22m\u001b[0m\u001b[1mr\u001b[22m\u001b[0m\u001b[1mi\u001b[22m\u001b[0m\u001b[1mt\u001b[22m\u001b[0m\u001b[1my\u001b[22m\n",
      "\n"
     ]
    },
    {
     "data": {
      "text/latex": [
       "\\texttt{struct  ManyElectron.RestrictParity  <: AbstractConfigurationRestriction}        ... restrict to configurations with a given parity.\n",
       "\n",
       "\\begin{verbatim}\n",
       "+ parity        ::Basics.Parity   ... given parity.\n",
       "\\end{verbatim}\n"
      ],
      "text/markdown": [
       "`struct  ManyElectron.RestrictParity  <: AbstractConfigurationRestriction`        ... restrict to configurations with a given parity.\n",
       "\n",
       "```\n",
       "+ parity        ::Basics.Parity   ... given parity.\n",
       "```\n"
      ],
      "text/plain": [
       "  \u001b[36mstruct  ManyElectron.RestrictParity  <: AbstractConfigurationRestriction\u001b[39m ...\n",
       "  restrict to configurations with a given parity.\n",
       "\n",
       "\u001b[36m  + parity        ::Basics.Parity   ... given parity.\u001b[39m"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "?RestrictParity"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "which just takes `Basics.plus` or `Basic.minus` and tells the program to restrict the list of configuration to the given parity: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "82-element Array{Configuration,1}:\n",
       " Configuration: 1s^2 2s^2 2p^6 3s^1 3p^6                \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^1 3p^5 4p^1           \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^1 3p^5 4f^1           \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^4 3d^1           \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^4 4s^1           \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^4 4d^1           \n",
       " Configuration: 1s^2 2s^2 2p^6 3p^6 3d^1                \n",
       " Configuration: 1s^2 2s^2 2p^6 3p^6 4s^1                \n",
       " Configuration: 1s^2 2s^2 2p^6 3p^6 4d^1                \n",
       " Configuration: 1s^2 2s^2 2p^6 3p^5 3d^1 4p^1           \n",
       " Configuration: 1s^2 2s^2 2p^6 3p^5 3d^1 4f^1           \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^1 3p^4 3d^2           \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^1 3p^4 3d^1 4s^1      \n",
       " ⋮                                                      \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^2 3d^1 4p^1 4f^1 \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^2 3d^1 4d^2      \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^2 3d^1 4f^2      \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^2 4s^2 4d^1      \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^2 4s^1 4p^2      \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^2 4s^1 4p^1 4f^1 \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^2 4s^1 4d^2      \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^2 4s^1 4f^2      \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^2 4p^2 4d^1      \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^2 4p^1 4d^1 4f^1 \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^2 4d^3           \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^2 4d^1 4f^2      "
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "restrictions = AbstractConfigurationRestriction[RestrictParity(Basics.plus)]\n",
    "wa = Basics.generateConfigurations(refConfigs, fromShells, toShells, 3, restrictions=restrictions)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "and where only configurations with even parity are returned. Since each restriction in the array `AbstractConfigurationRestriction[]`is applied independently, no configuration is generated if both restrictions are specified: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0-element Array{Configuration,1}"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "restrictions = AbstractConfigurationRestriction[RestrictParity(Basics.plus), RestrictParity(Basics.minus)]\n",
    "Basics.generateConfigurations(refConfigs, fromShells, toShells, 3, restrictions=restrictions)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The restriction concern all the occupation of shells in different ways. The restriction:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "search: \u001b[0m\u001b[1mR\u001b[22m\u001b[0m\u001b[1me\u001b[22m\u001b[0m\u001b[1ms\u001b[22m\u001b[0m\u001b[1mt\u001b[22m\u001b[0m\u001b[1mr\u001b[22m\u001b[0m\u001b[1mi\u001b[22m\u001b[0m\u001b[1mc\u001b[22m\u001b[0m\u001b[1mt\u001b[22m\u001b[0m\u001b[1mN\u001b[22m\u001b[0m\u001b[1mo\u001b[22m\u001b[0m\u001b[1mE\u001b[22m\u001b[0m\u001b[1ml\u001b[22m\u001b[0m\u001b[1me\u001b[22m\u001b[0m\u001b[1mc\u001b[22m\u001b[0m\u001b[1mt\u001b[22m\u001b[0m\u001b[1mr\u001b[22m\u001b[0m\u001b[1mo\u001b[22m\u001b[0m\u001b[1mn\u001b[22m\u001b[0m\u001b[1ms\u001b[22m\u001b[0m\u001b[1mT\u001b[22m\u001b[0m\u001b[1mo\u001b[22m\n",
      "\n"
     ]
    },
    {
     "data": {
      "text/latex": [
       "\\texttt{struct  ManyElectron.RestrictNoElectronsTo  <: AbstractConfigurationRestriction}        ... restrict the number of electron in all shells with principal quantum number n >= nmin or orbital angular momentum l >= lmin          to a total of ne electrons.\n",
       "\n",
       "\\begin{verbatim}\n",
       "+ ne            ::Int64     ... maximum number of (allowed) electrons in the specicied higher subshells.\n",
       "+ nmin          ::Int64     ... principal quantum number nmin.\n",
       "+ lmin          ::Int64     ... orbital angular momentum lmin.\n",
       "\\end{verbatim}\n"
      ],
      "text/markdown": [
       "`struct  ManyElectron.RestrictNoElectronsTo  <: AbstractConfigurationRestriction`        ... restrict the number of electron in all shells with principal quantum number n >= nmin or orbital angular momentum l >= lmin          to a total of ne electrons.\n",
       "\n",
       "```\n",
       "+ ne            ::Int64     ... maximum number of (allowed) electrons in the specicied higher subshells.\n",
       "+ nmin          ::Int64     ... principal quantum number nmin.\n",
       "+ lmin          ::Int64     ... orbital angular momentum lmin.\n",
       "```\n"
      ],
      "text/plain": [
       "  \u001b[36mstruct  ManyElectron.RestrictNoElectronsTo  <:\n",
       "  AbstractConfigurationRestriction\u001b[39m ... restrict the number of electron in all\n",
       "  shells with principal quantum number n >= nmin or orbital angular momentum l\n",
       "  >= lmin to a total of ne electrons.\n",
       "\n",
       "\u001b[36m  + ne            ::Int64     ... maximum number of (allowed) electrons in the specicied higher subshells.\u001b[39m\n",
       "\u001b[36m  + nmin          ::Int64     ... principal quantum number nmin.\u001b[39m\n",
       "\u001b[36m  + lmin          ::Int64     ... orbital angular momentum lmin.\u001b[39m"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "?RestrictNoElectronsTo"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "allows to specify minimum principal ($n_\\textrm{min}$) and orbital quantum number ($l_\\textrm{min}$) so that only configuration swith less or even ne electrons in all the shells $n >= n_\\textrm{min}$ *or*  $l >= l_\\textrm{min}$ are considered. Note that all shells, including core shells, are taken into account and, hence, $l_\\textrm{min}$ should not be chosen too small. Similarly, the restriction:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "search: \u001b[0m\u001b[1mR\u001b[22m\u001b[0m\u001b[1me\u001b[22m\u001b[0m\u001b[1mq\u001b[22m\u001b[0m\u001b[1mu\u001b[22m\u001b[0m\u001b[1me\u001b[22m\u001b[0m\u001b[1ms\u001b[22m\u001b[0m\u001b[1mt\u001b[22m\u001b[0m\u001b[1mM\u001b[22m\u001b[0m\u001b[1mi\u001b[22m\u001b[0m\u001b[1mn\u001b[22m\u001b[0m\u001b[1mi\u001b[22m\u001b[0m\u001b[1mm\u001b[22m\u001b[0m\u001b[1mu\u001b[22m\u001b[0m\u001b[1mm\u001b[22m\u001b[0m\u001b[1mO\u001b[22m\u001b[0m\u001b[1mc\u001b[22m\u001b[0m\u001b[1mc\u001b[22m\u001b[0m\u001b[1mu\u001b[22m\u001b[0m\u001b[1mp\u001b[22m\u001b[0m\u001b[1ma\u001b[22m\u001b[0m\u001b[1mt\u001b[22m\u001b[0m\u001b[1mi\u001b[22m\u001b[0m\u001b[1mo\u001b[22m\u001b[0m\u001b[1mn\u001b[22m\n",
      "\n"
     ]
    },
    {
     "data": {
      "text/latex": [
       "\\texttt{struct  ManyElectron.RequestMinimumOccupation  <: AbstractConfigurationRestriction}        ... request a minimum occupation ne in the given (list of) shells. \n",
       "\n",
       "\\begin{verbatim}\n",
       "+ ne            ::Int64           ... minimum electron occupation.\n",
       "+ shells        ::Array{Shell,1}  ... list of shells.\n",
       "\\end{verbatim}\n"
      ],
      "text/markdown": [
       "`struct  ManyElectron.RequestMinimumOccupation  <: AbstractConfigurationRestriction`        ... request a minimum occupation ne in the given (list of) shells. \n",
       "\n",
       "```\n",
       "+ ne            ::Int64           ... minimum electron occupation.\n",
       "+ shells        ::Array{Shell,1}  ... list of shells.\n",
       "```\n"
      ],
      "text/plain": [
       "  \u001b[36mstruct  ManyElectron.RequestMinimumOccupation  <:\n",
       "  AbstractConfigurationRestriction\u001b[39m ... request a minimum occupation ne in the\n",
       "  given (list of) shells. \n",
       "\n",
       "\u001b[36m  + ne            ::Int64           ... minimum electron occupation.\u001b[39m\n",
       "\u001b[36m  + shells        ::Array{Shell,1}  ... list of shells.\u001b[39m"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "?RequestMinimumOccupation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "requests that the total occupation of all shells in `shells` is larger or equal than the given `ne`, and analogously for the restriction:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "search: \u001b[0m\u001b[1mR\u001b[22m\u001b[0m\u001b[1me\u001b[22m\u001b[0m\u001b[1mq\u001b[22m\u001b[0m\u001b[1mu\u001b[22m\u001b[0m\u001b[1me\u001b[22m\u001b[0m\u001b[1ms\u001b[22m\u001b[0m\u001b[1mt\u001b[22m\u001b[0m\u001b[1mM\u001b[22m\u001b[0m\u001b[1ma\u001b[22m\u001b[0m\u001b[1mx\u001b[22m\u001b[0m\u001b[1mi\u001b[22m\u001b[0m\u001b[1mm\u001b[22m\u001b[0m\u001b[1mu\u001b[22m\u001b[0m\u001b[1mm\u001b[22m\u001b[0m\u001b[1mO\u001b[22m\u001b[0m\u001b[1mc\u001b[22m\u001b[0m\u001b[1mc\u001b[22m\u001b[0m\u001b[1mu\u001b[22m\u001b[0m\u001b[1mp\u001b[22m\u001b[0m\u001b[1ma\u001b[22m\u001b[0m\u001b[1mt\u001b[22m\u001b[0m\u001b[1mi\u001b[22m\u001b[0m\u001b[1mo\u001b[22m\u001b[0m\u001b[1mn\u001b[22m\n",
      "\n"
     ]
    },
    {
     "data": {
      "text/latex": [
       "\\texttt{struct  ManyElectron.RequestMaximumOccupation  <: AbstractConfigurationRestriction}        ... request a maximum occupation ne in the given (list of) shells. \n",
       "\n",
       "\\begin{verbatim}\n",
       "+ ne            ::Int64           ... maximum electron occupation.\n",
       "+ shells        ::Array{Shell,1}  ... list of shells.\n",
       "\\end{verbatim}\n"
      ],
      "text/markdown": [
       "`struct  ManyElectron.RequestMaximumOccupation  <: AbstractConfigurationRestriction`        ... request a maximum occupation ne in the given (list of) shells. \n",
       "\n",
       "```\n",
       "+ ne            ::Int64           ... maximum electron occupation.\n",
       "+ shells        ::Array{Shell,1}  ... list of shells.\n",
       "```\n"
      ],
      "text/plain": [
       "  \u001b[36mstruct  ManyElectron.RequestMaximumOccupation  <:\n",
       "  AbstractConfigurationRestriction\u001b[39m ... request a maximum occupation ne in the\n",
       "  given (list of) shells. \n",
       "\n",
       "\u001b[36m  + ne            ::Int64           ... maximum electron occupation.\u001b[39m\n",
       "\u001b[36m  + shells        ::Array{Shell,1}  ... list of shells.\u001b[39m"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "?RequestMaximumOccupation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "with regard to the maximum number of electrons in `shells`. In our example from above, we can therefore easily specify that we wish to restrict ourselves to configurations with (1) even parity, (2) not more than one electron in an $l >= 3$ shell ($f$-shell) and with at least 5 electrons in $3s,\\: 3p$:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "29-element Array{Configuration,1}:\n",
       " Configuration: 1s^2 2s^2 2p^6 3s^1 3p^6           \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^1 3p^5 4p^1      \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^1 3p^5 4f^1      \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^4 3d^1      \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^4 4s^1      \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^4 4d^1      \n",
       " Configuration: 1s^2 2s^2 2p^6 3p^6 3d^1           \n",
       " Configuration: 1s^2 2s^2 2p^6 3p^6 4s^1           \n",
       " Configuration: 1s^2 2s^2 2p^6 3p^6 4d^1           \n",
       " Configuration: 1s^2 2s^2 2p^6 3p^5 3d^1 4p^1      \n",
       " Configuration: 1s^2 2s^2 2p^6 3p^5 3d^1 4f^1      \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^1 3p^4 3d^2      \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^1 3p^4 3d^1 4s^1 \n",
       " ⋮                                                 \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^1 3p^4 4s^1 4d^1 \n",
       " Configuration: 1s^2 2s^2 2p^6 3p^5 4p^1 4d^1      \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^1 3p^4 4p^2      \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^1 3p^4 4p^1 4f^1 \n",
       " Configuration: 1s^2 2s^2 2p^6 3p^5 4d^1 4f^1      \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^1 3p^4 4d^2      \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^3 3d^1 4p^1 \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^3 3d^1 4f^1 \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^3 4s^1 4p^1 \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^3 4s^1 4f^1 \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^3 4p^1 4d^1 \n",
       " Configuration: 1s^2 2s^2 2p^6 3s^2 3p^3 4d^1 4f^1 "
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "restrictions = AbstractConfigurationRestriction[RestrictParity(Basics.plus), RestrictNoElectronsTo(1, 5, 3),\n",
    "                                                RequestMinimumOccupation(5, [Shell(\"3s\"), Shell(\"3p\")]) ]\n",
    "Basics.generateConfigurations(refConfigs, fromShells, toShells, 3, restrictions=restrictions)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This shows that the number of configurations can be significantly reduced by specifying proper restrictions. The same restrictions can be applied to any given list of configurations if `noex = 0` is chosen in the call above, i.e. if no additional replacements are made. Moreover, since each of these restrictions are *tested* independently, its quite easy to add further restrictions if the user applies different computational models (or a different language) in specifying configurations of interest. However, already the presently available **restrictions** has been found useful in order to construct lists of configurations for dealing with Rydberg levels or for dielectronic recombination studies."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "@webio": {
   "lastCommId": null,
   "lastKernelId": null
  },
  "kernelspec": {
   "display_name": "Julia 1.0.3",
   "language": "julia",
   "name": "julia-1.0"
  },
  "language_info": {
   "file_extension": ".jl",
   "mimetype": "application/julia",
   "name": "julia",
   "version": "1.0.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}