{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "681fb4de",
   "metadata": {},
   "source": [
    "# Adding custom models to pymagglobal permanently"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7c938d6b",
   "metadata": {},
   "source": [
    "The command line interface provides an option to add your own models to `pymagglobal` permanently. This feature is somewhat experimental, so please contact us, if you run into trouble. The models will be added only locally. Below we show several approaches, how models can be added to `pymagglobal`."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "620a2b05",
   "metadata": {},
   "source": [
    "## Adding a single model"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "13988168",
   "metadata": {},
   "source": [
    "The most straight-forward way to add a model is probably calling `pymagglobal` and providing a name and path to the model file. Say you have a model called `MyModel1k` at `/home/name/models/my_model_1k.dat`. Then you can permanently include this model via:\n",
    "```\n",
    "$ pymagglobal --add-model MyModel1k /home/name/models/my_model_1k.dat\n",
    "```\n",
    "\n",
    "Internally, name and path are stored in a file in `pymagglobal`'s data-directory. The model will now be included in the model list, as well as calls to `built_in_models` from the python backend. Whenever `built_in_models` is called, a check is performed and models that no longer exist at the specified path are removed from the list."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "18550fd8",
   "metadata": {},
   "source": [
    "## Adding multiple models at once"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "be2cfa01",
   "metadata": {},
   "source": [
    "There are two ways to add multiple models at once. You can either pass the path to a directory, in which case all files in the directory will be considered model files and added to the list. The filenames will be used as model names. To do this in the above case, one would use\n",
    "```\n",
    "$ pymagglobal --add-model /home/name/models/\n",
    "```\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "db42cded",
   "metadata": {},
   "source": [
    "The other way is passing a file that contains a list of models and paths, seperated by comma and one model per line. So if you have a file `model_list.txt` at `/home/name/` that looks like this\n",
    "\n",
    "```\n",
    "MyModel1k,/home/name/models/my_model_1k.dat\n",
    "```\n",
    "you can pass that file to pymagglobal via\n",
    "```\n",
    "$ pymagglobal --add-model /home/name/model_list.txt\n",
    "```\n",
    "to add all models listed in the file. Internally, the file is simply appended to pymagglobals custom models file and a cleanup will be performed by calling `built_in_models`."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.9.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}