{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Usage\n",
    "\n",
    "Whenever you want to use picometer, first re-activate the virtual environment created during installation following instructions therein. Running the program with no arguments produces the help string."
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "python -m picometer"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "usage: picometer [-h] filename\n",
    "\n",
    "Precisely define and measure across multiple crystal structures\n",
    "\n",
    "positional arguments:\n",
    "  filename    Path to yaml file with routine settings and instructions\n",
    "\n",
    "options:\n",
    "  -h, --help  show this help message and exit\n",
    "\n",
    "Author: Daniel Tchoń, baharis @ GitHub"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Picometer inputs its settings and instructions from an input\n",
    "[`.yaml`](https://en.wikipedia.org/wiki/YAML) file.\n",
    "The file can contain a dictionary of `settings`,\n",
    "as well as a list of `instructions`.\n",
    "The list of instructions, called also a \"routine\", must include\n",
    "only single-element maps in the `- instruction: detail`\n",
    "or `- instruction: {details}` format.\n",
    "Examples of instruction files are available in the `tests` directory.\n",
    "The easiest way to generate your file is to prepare it based\n",
    "on the example provided."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Instructions\n",
    "\n",
    "The following instructions are currently supported by picometer (as of version 0.1.2):\n",
    "- **Input/output instructions**\n",
    "  - `load` model from a cif file, given `filename` or mapping syntax:\n",
    "    `{path: filename.cif, block: cif_block}`.\n",
    "  - `write` table with all evaluations to a csv file.\n",
    "- **Selection instructions**\n",
    "  - `select` atoms, groups, or shapes to be used; use raw element names\n",
    "    or provide symmetry relation / recenter using mapping syntax, for example:\n",
    "    `{label: C(11), symm: x;-y;z+1/2, at: Fe(1)}`.\n",
    "    By default, selection is cleared after calling `select` with no arguments\n",
    "    or calling an aggregating or evaluating instruction.\n",
    "  - `recenter` selection around a new centroid;\n",
    "      this action is applied to every selected item individually,\n",
    "      so to recenter fixed group of atoms, `group` them first and recenter\n",
    "      this group - otherwise you will recenter individual atoms instead.\n",
    "- **Aggregation instructions**\n",
    "  - `group` current selection into a new object with fixed elements.\n",
    "  - fit `centroid` to the current atom / centroid selection;\n",
    "  - fit `line` to the current atom / centroid selection;\n",
    "  - fit `plane` to the currect atom / centroid selection;\n",
    "- **Evaluation instructions**\n",
    "  - measure `distance` between 2 selected objects; if the selection includes\n",
    "    groups of atoms, measure closes distance to the group of atoms.\n",
    "  - measure `angle` between 2–6 selected objects; if the selection includes\n",
    "    (ordered) atoms, calculate direct or dihedral angle between presumed bonds."
   ]
  }
 ],
 "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.10.11"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}