{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "delayed-biodiversity",
   "metadata": {},
   "source": [
    "# Quick start\n",
    "This section is a quick start guide that will show the basic functionality of McStasScript. It assumes the user is already familiar with McStas itself, if this is not the case, it is recommended to start with the tutorial which can serve as an introduction to both McStas and McStasScript.\n",
    "\n",
    "## Importing the package\n",
    "McStasScript needs to be imported into the users python environment."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "dense-internet",
   "metadata": {},
   "outputs": [],
   "source": [
    "import mcstasscript as ms"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "exotic-sandwich",
   "metadata": {},
   "source": [
    "## Creating the first instrument object\n",
    "Now the package can be used. Start with creating a new instrument, just needs a name. For a McXtrace instrument use McXtrace_instr instead."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "disabled-canon",
   "metadata": {},
   "outputs": [],
   "source": [
    "instrument = ms.McStas_instr(\"first_instrument\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "known-depression",
   "metadata": {},
   "source": [
    "### Finding a component\n",
    "The instrument object loads the available McStas components, so it can show these in order to help the user."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "adult-assignment",
   "metadata": {},
   "outputs": [],
   "source": [
    "instrument.available_components()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fatal-climate",
   "metadata": {},
   "outputs": [],
   "source": [
    "instrument.available_components(\"sources\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "powerful-rover",
   "metadata": {},
   "source": [
    "### Adding the first component\n",
    "McStas components can be added to the instrument, here we add a source and ask for help on the parameters."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "instructional-liquid",
   "metadata": {},
   "outputs": [],
   "source": [
    "source = instrument.add_component(\"source\", \"Source_simple\")\n",
    "source.show_parameters()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "noble-colleague",
   "metadata": {},
   "source": [
    "### Set parameters\n",
    "The parameters of the component object are adjustable directly through the attributes of the object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "continued-denial",
   "metadata": {},
   "outputs": [],
   "source": [
    "source.xwidth = 0.03\n",
    "source.yheight = 0.03\n",
    "source.lambda0 = 3\n",
    "source.dlambda = 2.2\n",
    "source.dist = 5\n",
    "source.focus_xw = 0.01\n",
    "source.focus_yh = 0.01\n",
    "print(source)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "interior-better",
   "metadata": {},
   "source": [
    "### Instrument parameters\n",
    "It is possible to add instrument parameters that can be adjusted when running the simulation or adjusted using the widget interface."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "atlantic-capital",
   "metadata": {},
   "outputs": [],
   "source": [
    "wavelength = instrument.add_parameter(\"wavelength\", value=3, comment=\"Wavelength in AA\")\n",
    "source.lambda0 = wavelength\n",
    "source.dlambda = \"0.1*wavelength\"\n",
    "print(source)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "practical-somewhere",
   "metadata": {},
   "source": [
    "### Inserting a sample component\n",
    "A sample component is added as any other component, but here we place it relative to the source. A SANS sample is used, it focuses to a detector (chosen with target_index) with a width of focus_xw and height of focus_yh."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "changing-funds",
   "metadata": {},
   "outputs": [],
   "source": [
    "sample = instrument.add_component(\"sans_sample\", \"Sans_spheres\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "after-reliance",
   "metadata": {},
   "outputs": [],
   "source": [
    "sample.set_AT(5, RELATIVE=source)\n",
    "sample.set_parameters(R=120, xwidth=0.01, yheight=0.01, zdepth=0.01,\n",
    "                      target_index=1, focus_xw=0.5, focus_yh=0.5)\n",
    "print(sample)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "million-shoot",
   "metadata": {},
   "source": [
    "### Adding a monitor\n",
    "The monitor can be placed relative to the sample, and even use the attributes from the sample to define its size so that the two always match. When setting a filename, it has to be a string also in the generated code, so use double quotation marks as shown here."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "characteristic-spectacular",
   "metadata": {},
   "outputs": [],
   "source": [
    "PSD = instrument.add_component(\"PSD\", \"PSD_monitor\")\n",
    "PSD.set_AT([0, 0, 5], RELATIVE=sample)\n",
    "PSD.set_parameters(xwidth=sample.focus_xw, yheight=sample.focus_yh, filename='\"PSD.dat\"')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "mechanical-burlington",
   "metadata": {},
   "source": [
    "## Setting up the simulation\n",
    "The instrument now contains a source, a sample and a monitor, this is enough for a simple demonstration."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "wicked-terrorism",
   "metadata": {},
   "outputs": [],
   "source": [
    "instrument.show_parameters()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "postal-advocate",
   "metadata": {},
   "outputs": [],
   "source": [
    "instrument.set_parameters(wavelength=4)\n",
    "instrument.settings(ncount=2E6)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "requested-translation",
   "metadata": {},
   "source": [
    "### Performing the simulation\n",
    "In order to start the simulation the *backengine* method is called. If the simulation is successful, the data will be returned, otherwise the method returns None."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "durable-printer",
   "metadata": {},
   "outputs": [],
   "source": [
    "data = instrument.backengine()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "frozen-circle",
   "metadata": {},
   "source": [
    "## Plot the data\n",
    "The data can be plotted with the *make_sub_plot* function from the plotter module."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "christian-detail",
   "metadata": {},
   "outputs": [],
   "source": [
    "ms.make_sub_plot(data, log=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "critical-rebound",
   "metadata": {},
   "source": [
    "### Access the data\n",
    "The data is a list of McStasData objects and can be accessed directly."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "gothic-water",
   "metadata": {},
   "outputs": [],
   "source": [
    "print(data)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "common-overhead",
   "metadata": {},
   "source": [
    "It is possible to search through the data list with the *name_search* function to retrieve the desired data object. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "colonial-thompson",
   "metadata": {},
   "outputs": [],
   "source": [
    "PSD_data = ms.name_search(\"PSD\", data)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "american-crash",
   "metadata": {},
   "source": [
    "The intensities can then be accessed directly, along with Error and Ncount. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "exempt-lincoln",
   "metadata": {},
   "outputs": [],
   "source": [
    "PSD_data.Intensity"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "unavailable-secretariat",
   "metadata": {},
   "source": [
    "Metadata is also available as a dict."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "mediterranean-guatemala",
   "metadata": {},
   "outputs": [],
   "source": [
    "info_dict = PSD_data.metadata.info\n",
    "for field, info in info_dict.items():\n",
    "    print(field, \":\", info)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "coupled-sailing",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "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.8.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}