{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Tutorial 03: Defining energy and dynamics parameters\n",
    "\n",
    "> Interactive online tutorial:\n",
    "> [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/ubermag/micromagneticmodel/master?filepath=docs%2Fipynb%2Findex.ipynb)\n",
    "\n",
    "Every energy terms requires one or more input parameters for its definition. For example, (second order) uniaxial anisotropy energy requires the anisotropy constant $K$ and the anisotropy axis $\\mathbf{u}$. There are three ways how these parameters can be defined:\n",
    "\n",
    "## 1. Constant parameters\n",
    "\n",
    "If the energy parameters do not vary in space, they can be defined using constant values."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "K = 1e5\n",
    "u = (0, 0, 1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Parameters defined \"per region\"\n",
    "\n",
    "If different regions have different values of parameters, they can be defined \"per region\". Let us say there are two regions: \"region1\" and \"region2\". In \"region1\", the anisotropy constant is $5\\times10^{5} \\text{J}/\\text{m}^{3}$ and the anisotropy axis is $(1, 0, 0)$. On the other hand, in \"region2\", these parameters are $3\\times10^{5} \\text{J}/\\text{m}^{3}$ and $(0, 0, 1)$. These two parameters can then be defined using a dictionary:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "K = {'region1': 5e5, 'region2': 3e5}\n",
    "u = {'region1': (1, 0, 0), 'region2': (0, 0, 1)}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Certain energy terms also require the parameters to be defined between regions. This can be defined by adding an additional item to the dictionary with colon (`:`) in the key. For example, an exchange energy parameter can be:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "A = {'region1': 1e-12, 'region2': 2e-12, 'region1:region2': 1e-11}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Parameters defined using `discretisedfield.Field` object\n",
    "\n",
    "If it is not possible to define the energy parameter using a dictionary because ot varies in space in a non-trivial manner, a parameter can be defined using a field object. For instance:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "import discretisedfield as df\n",
    "\n",
    "p1 = (0, 0, 0)\n",
    "p2 = (50e-9, 50e-9, 50e-9)\n",
    "cell = (2e-9, 2e-9, 2e-9)\n",
    "mesh = df.Mesh(p1=p1, p2=p2, cell=cell)\n",
    "\n",
    "K = df.Field(mesh, dim=1)\n",
    "u = df.Field(mesh, dim=3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The values of these two (scalar and vector) fields can be then set using Python functions. For further details, plese refer to `discretisedfield` [documentation](https://discretisedfield.readthedocs.io/en/latest/).\n",
    "\n",
    "## Other\n",
    "\n",
    "Full description of all existing descriptors can be found in the [API Reference](https://micromagneticmodel.readthedocs.io/en/latest/?badge=latest)."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "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.7.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}