{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "3232ab03",
   "metadata": {},
   "source": [
    "# Usage\n",
    "\n",
    "Explicit example scripts can be found [here](https://github.com/matillda123/Pulse-Retrieval-with-JAX/tree/main/examples)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d474f173",
   "metadata": {},
   "source": [
    "## How to simulate a trace?  \n",
    "\n",
    "Through the `pulsedjax.simulate_trace` module artificial pulses as well as traces can be generated. This is fasciliated via the `MakeTrace(MakePulse)` class. Pulses can be defined via the predefined dataclasses `GaussianAmplitude`, `LorentzianAmplitude`, `PolynomialPhase`, `SinusoidalPhase`, `RandomPhase` and `MultiPulse`. In addition the `CustomPulse` can be used to provide an externally defined pulse."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "51c1b294",
   "metadata": {},
   "outputs": [],
   "source": [
    "from pulsedjax.simulate_trace import MakeTrace, GaussianAmplitude, PolynomialPhase\n",
    "\n",
    "amp = GaussianAmplitude(1, 0.3, 0.1, 1)\n",
    "phase = PolynomialPhase(0.3, (0,0,20,0))\n",
    "\n",
    "mp = MakeTrace(N=1024, f_max=2)\n",
    "time, frequency, pulse_t, pulse_f = mp.generate_pulse((amp, phase))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ff71d80e",
   "metadata": {},
   "source": [
    "Using a pulse and user specified measurement parameters a trace can be calculated."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "40a570bb",
   "metadata": {},
   "outputs": [],
   "source": [
    "# method has to be replaced with the method name\n",
    "theta, frequency, trace, spectra = mp.generate_method(time, frequency, pulse_t, pulse_f, ... )"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b890a90c",
   "metadata": {},
   "source": [
    "## How to run a retrieval?  \n",
    "\n",
    "All retrieval algorithm implementations follow the same pattern. During the class instantiation the measurement data and parameters as well as some or all algorithm parameters are provided."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "73a3ef2e",
   "metadata": {},
   "outputs": [],
   "source": [
    "from pulsedjax.method import algorithm\n",
    "\n",
    "myalgorithm = algorithm(theta, frequency, trace, nonlinear_method, ... )"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ba8da938",
   "metadata": {},
   "source": [
    "In addition measured spectra or a known gate pulse may optionally be provided."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "80f29758",
   "metadata": {},
   "outputs": [],
   "source": [
    "myalgorithm.use_measured_spectrum(frequency_spectrum, spectrum_pulse, \"pulse\")\n",
    "myalgorithm.use_measured_spectrum(frequency_spectrum, spectrum_gate_pulse, \"gate\")\n",
    "myalgorithm.get_gate_pulse(frequency_gate, pulse_f_gate) # needs to be in frequency domain"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "88ffdae4",
   "metadata": {},
   "source": [
    "Further algorithm parameters may be set via attributes or as described in [Nonlinear Optimization](example_nonlinear_optimization.ipynb).  \n",
    "An initial guess has to be created using `myalgorithm.create_initial_guess()`. Depending on the type of the algorithm the inputs to this function may differ. For a `ClassicalAlgorithm` the guess options are `\"random\"`, `\"random_phase\"`, `\"constant\"` and `\"constant_phase\"`. For a `GeneralAlgorithm` different options can be specified for the spectral amplitude and phase. For the amplitude these are `\"gaussian\"` and `\"lorentizan\"`. For the phase they are `\"polynomial\"`, `\"sinusoidal\"` and `\"sigmoidal\"`. The inputs `\"bsplines_k\"`, `\"constinuous\"` and the inputs for `ClassicalAlgorithm`s are available for both amplitude and phase. For B-Splines {cite}`uniform_bsplines` the order is defined via `k`. So 5th-order B-Splines are defined as `\"bsplines_5\"`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "cb252ad4",
   "metadata": {},
   "outputs": [],
   "source": [
    "# For a classical algorithm\n",
    "population = myalgorithm.create_initial_guess(population_size, guess_type)\n",
    "\n",
    "# For a general algorithm, no_funcs defines the number of basis functions\n",
    "population = myalgorithm.create_initial_guess(population_size, amp_type, phase_type, no_funcs_amp, no_funcs_phase)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d366f77b",
   "metadata": {},
   "source": [
    "Finally, the retrieval is run via the `myalgorithm.run()` function. Parts of the returned object can be visalized via `myalgorithm.plot_results()`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9d10e794",
   "metadata": {},
   "outputs": [],
   "source": [
    "final_result = myalgorithm.run(population, no_iterations)\n",
    "myalgorithm.plot_results(final_result)"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}