Merge pull request CederGroupHub#421 from lbluque/list-options

List basis set, mckernel, step type and bias options

docs/src/examples.rst

@@ -51,6 +51,7 @@ Advanced Examples
 - `Centering training data in stage-wise fit with electrostatics`_
 - `Adding structures to a StructureWrangler in parallel`_
 - `Simulated annealing with point electrostatics`_
+- `Choosing Monte Carlo kernels and step types`_
 - `Wang-Landau sampling of an FCC Ising model`_
 - `Generating special quasirandom structures`_
 - `Solving for periodic ground-states`_
@@ -64,6 +65,8 @@ Advanced Examples
 
 .. _Simulated annealing with point electrostatics: notebooks/running-ewald-sim_anneal.ipynb
 
+.. _Choosing Monte Carlo kernels and step types: notebooks/advanced-mc-settings.ipynb
+
 .. _Wang-Landau sampling of an FCC Ising model: notebooks/wang-landau-ising.ipynb
 
 .. _Generating special quasirandom structures: notebooks/generating-sqs.ipynb

docs/src/index.rst

@@ -31,7 +31,7 @@ crystalline materials.*
       :alt: PyPi Version
       :target: https://pypi.org/project/smol
 
-.. image:: https://img.shields.io/badge/python-3.8%2B-blue
+.. image:: https://img.shields.io/badge/python-3.9%2B-blue
       :alt: Python Versions
       :target: https://www.python.org/downloads/
 

docs/src/notebooks/advanced-mc-settings.ipynb

@@ -0,0 +1,202 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "0e321a87-9cdf-4e19-b63d-7c489c22f2ce",
+   "metadata": {
+    "tags": []
+   },
+   "source": [
+    "# Advanced Monte Carlo settings - kernels and steps\n",
+    "\n",
+    "**smol** allows a lot of flexibility to set and control the specifics of montecarlo simulations, these are implemented in three types of helper classes that can be set when creating a sampler:\n",
+    "\n",
+    "- [`MCKernels`](https://cedergrouphub.github.io/smol/api_reference/moca/kernel.kernels.html) define the Monte Carlo sampling algorithm\n",
+    "- [`MCUshers`](https://cedergrouphub.github.io/smol/api_reference/moca/kernel.mcusher.html) specify the type of step or transition."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "5c7cd3a0-b8a9-44e6-9f5a-3b79d4244f7c",
+   "metadata": {
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "import numpy as np\n",
+    "import json\n",
+    "from smol.io import load_work\n",
+    "from smol.moca import Ensemble, Sampler, available_mckernels, available_step_types, available_bias_types"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2a4185f7-d67d-4192-97cf-a042c71d7d8c",
+   "metadata": {
+    "tags": []
+   },
+   "source": [
+    "### 0) Load the previous LNO CE with electrostatics"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "1ddde958-cd79-40eb-9417-4240a10de2c9",
+   "metadata": {
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "work = load_work('./data/basic_ce_ewald.mson')\n",
+    "expansion = work['ClusterExpansion']"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1c0a79db-6ddc-4e75-8152-eac5d8075bc8",
+   "metadata": {},
+   "source": [
+    "### 1) Create a semigrand ensemble\n",
+    "The `Ensemble` class can also be used to run semigrand canonical MC by fixing relative chemical potentials."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "ecc83016-42db-4038-a48e-f884f6345cd9",
+   "metadata": {
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "from smol.moca import Ensemble\n",
+    "\n",
+    "sc_matrix = np.array([\n",
+    "    [6, 1, 1],\n",
+    "    [1, 2, 1],\n",
+    "    [1, 1, 2]\n",
+    "])\n",
+    "\n",
+    "chemical_potentials = {'Li+': 0, 'Vacancy': 0, 'Ni3+': 0, 'Ni4+': 0}\n",
+    "\n",
+    "ensemble = Ensemble.from_cluster_expansion(\n",
+    "    expansion, sc_matrix, chemical_potentials=chemical_potentials\n",
+    ")\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d8163845-03f7-4e5a-ac1f-25894682f39b",
+   "metadata": {},
+   "source": [
+    "### 2) List the available classes"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "ccaf87c4-8095-4502-91b6-19ae45e5c2fd",
+   "metadata": {
+    "tags": []
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "The available Monte Carlo kernels are:\n",
+      "('metropolis', 'uniformly-random', 'wang-landau', 'multicell-metropolis')\n",
+      "\n",
+      "The available Monte Carlo step types are:\n",
+      "('flip', 'swap', 'multi-step', 'composite', 'table-flip')\n",
+      "\n"
+     ]
+    }
+   ],
+   "source": [
+    "print(f\"The available Monte Carlo kernels are:\\n{available_mckernels()}\\n\")\n",
+    "print(f\"The available Monte Carlo step types are:\\n{available_step_types()}\\n\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "9f77237b-d034-45c1-b214-b08461496e64",
+   "metadata": {},
+   "source": [
+    "### 3) Choosing the kernel and step type\n",
+    "\n",
+    "The specific choices of each of the above can be done when initializing a Sampler.\n",
+    "\n",
+    "Specific options for the kernel and the step type are passed as additional keyword arguments."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 16,
+   "id": "874eca41-fc04-490e-af3d-f1d93f8cd46c",
+   "metadata": {
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "from smol.moca.kernel.mcusher import Flip\n",
+    "\n",
+    "flip = Flip(ensemble.processor.get_sublattices())\n",
+    "\n",
+    "sampler = Sampler.from_ensemble(\n",
+    "    ensemble,\n",
+    "    # kernel settings\n",
+    "    kernel_type=\"metropolis\",  # this is the default value\n",
+    "    temperature=1000,\n",
+    "    # step type settings\n",
+    "    step_type=\"multi-step\", #  make sure the step type is valid if giving chemical potentials\n",
+    "    mcusher=flip,  # look at the documentation of Multistep to see the options\n",
+    "    step_lengths=5,  # each step will be composed of 5 random flips\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 26,
+   "id": "b1a7e6c7-7eaf-4218-8dd8-c4b162bf898b",
+   "metadata": {
+    "tags": []
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Metadata(chemical_potentials={Species Li+: 0, Vacancy vacA0+: 0, Species Ni3+: 0, Species Ni4+: 0}, cls_name='SampleContainer', kernels=[Metadata(seed=274324443849665987189735601095705236747, step=Metadata(sublattices=[(Species Li+, Vacancy vacA0+), (Species Ni3+, Species Ni4+), (Species O2-,)], sublattice_probabilities=array([0.5, 0.5]), cls_name='MultiStep', step=Metadata(sublattices=[(Species Li+, Vacancy vacA0+), (Species Ni3+, Species Ni4+), (Species O2-,)], sublattice_probabilities=array([0.5, 0.5]), cls_name='Flip'), step_lengths=array([5]), step_probabilities=array([1.])), cls_name='Metropolis')])\n"
+     ]
+    }
+   ],
+   "source": [
+    "print(sampler.samples.metadata)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "matx_dev",
+   "language": "python",
+   "name": "matx_dev"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.11"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}