[WIP] Add support for MPContribs.

.github/workflows/continuous-integration-pip.yml

@@ -64,6 +64,7 @@ jobs:
           python -m pip install --upgrade pip
           pip install pytest cython setuptools  pytest-cov sympy
           pip install -r requirements.txt
+          pip install numpy -U
 
       - name: Build and install package from source
         run: python setup.py develop
@@ -143,6 +144,7 @@ jobs:
         run: |
           conda --version
           which python
+          pip install numpy -U
           python setup.py develop
       - name: Test with pytest
         shell: pwsh

.gitignore

@@ -117,6 +117,7 @@ class-diagram*
 *.csdf
 *.csdfe
 *.mrsys
+*.json.gz
 test_os.py
 note.txt
 simulate_lineshape.py

docs/api_py/py-utilities.rst

@@ -0,0 +1,32 @@
+.. _fitting_api:
+
+Utilities API
+=============
+
+LMFIT Utilities
+---------------
+
+.. currentmodule:: mrsimulator.utils.spectral_fitting
+
+.. autofunction:: make_LMFIT_params
+.. autofunction:: LMFIT_min_function
+.. autofunction:: bestfit
+.. autofunction:: residuals
+
+
+mpcontribs Utilities
+--------------------
+
+.. currentmodule:: mrsimulator.contribs
+
+.. autofunction:: mpcontribs_export
+
+
+.. currentmodule:: mrsimulator.contribs.base
+
+.. autoclass:: ChemicalShiftSchema
+.. autoclass:: QuadrupolarSchema
+.. autoclass:: SiteSchema
+.. autoclass:: MethodSchema
+.. autoclass:: SimulatorSchema
+.. autoclass:: ContribSchema

docs/index.rst

@@ -232,7 +232,7 @@ API and references
     api_py/py-simulator
     api_py/py-signal-processing
     api_py/py-model
-    api_py/py-fitting
+    api_py/py-utilities
     api_c/c_api
 
 

docs/installation/requirements.rst

@@ -7,7 +7,7 @@ Package dependencies
 
 **Required packages**
 
-- `NumPy>=1.17 <http://www.numpy.org>`_
+- `numpy>=1.17 <http://www.numpy.org>`_
 - openblas
 - cython>=0.29.14
 - typing-extensions>=3.7

docs/notebooks/fitting/1D_fitting/plot_2_xonotlite.ipynb

@@ -0,0 +1,230 @@
+{
+  "cells": [
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "# This cell is added by sphinx-gallery\n!pip install mrsimulator --quiet\n\n\n%matplotlib inline\n\nimport mrsimulator\nprint(f'You are using mrsimulator v{mrsimulator.__version__}')"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "\n# 29Si 1D MAS spinning sideband (Xonotlite)\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "The following is an example for submitting the NMR tensor parameters to mpcontribs.\nWe use the $^{29}\\text{Si}$ 1D MAS NMR spectrum of Xonotlite crystal by Hansen\net al. [#f1]_ for demonstration.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "import csdmpy as cp\nimport matplotlib.pyplot as plt\nfrom lmfit import Minimizer\n\nfrom mrsimulator import Simulator, SpinSystem, Site\nfrom mrsimulator.methods import BlochDecaySpectrum\nfrom mrsimulator import signal_processing as sp\nfrom mrsimulator.utils import spectral_fitting as sf\nfrom mrsimulator.utils import get_spectral_dimensions"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Import the dataset\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "filename = \"https://sandbox.zenodo.org/record/744498/files/xonotlite.csdf\"\nexperiment = cp.load(filename).real\n\n# standard deviation of noise from the dataset\nsigma = 2.819601\n\n# Convert the coordinates along each dimension from Hz to ppm.\n_ = [item.to(\"ppm\", \"nmr_frequency_ratio\") for item in experiment.dimensions]\n\n# Plot of the synthetic dataset.\nplt.figure(figsize=(4.25, 3.0))\nax = plt.subplot(projection=\"csdm\")\nax.plot(experiment, \"k\", alpha=0.5)\nax.invert_xaxis()\nplt.tight_layout()\nplt.show()"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Create a fitting model\n**Guess model**\n\nCreate a guess list of spin systems. There are three crystallographic\n$^{29}\\text{Si}$ sites in Xonotlite.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "s1 = Site(\n    isotope=\"29Si\",\n    isotropic_chemical_shift=-97.17,  # in ppm,\n    shielding_symmetric={\"zeta\": 35.0, \"eta\": 0.0},  # zeta in ppm\n)\ns2 = Site(\n    isotope=\"29Si\",\n    isotropic_chemical_shift=-86.3,  # in ppm,\n    shielding_symmetric={\"zeta\": 50.0, \"eta\": 0.5},  # zeta in ppm\n)\ns3 = Site(\n    isotope=\"29Si\",\n    isotropic_chemical_shift=-87.2,  # in ppm,\n    shielding_symmetric={\"zeta\": 44.0, \"eta\": 0.5},  # zeta in ppm\n)\nspin_systems = [\n    SpinSystem(name=\"Q3\", sites=[s1], abundance=25),\n    SpinSystem(name=\"Q2 (1)\", sites=[s2], abundance=75 / 2),\n    SpinSystem(name=\"Q2 (2)\", sites=[s3], abundance=75 / 2),\n]"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "**Method**\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "# Get the spectral dimension paramters from the experiment.\nspectral_dims = get_spectral_dimensions(experiment)\n\nmethod = BlochDecaySpectrum(\n    channels=[\"29Si\"],\n    magnetic_flux_density=14.1,  # in T\n    rotor_frequency=1800.0,  # in Hz\n    spectral_dimensions=spectral_dims,\n    experiment=experiment,  # add the measurement to the method.\n)\n\n# Optimize the script by pre-setting the transition pathways for each spin system from\n# the das method.\nfor sys in spin_systems:\n    sys.transition_pathways = method.get_transition_pathways(sys)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "**Guess Spectrum**\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "# Simulation\n# ----------\nsim = Simulator(spin_systems=spin_systems, methods=[method])\nsim.run()\n\n# Post Simulation Processing\n# --------------------------\nprocessor = sp.SignalProcessor(\n    operations=[\n        sp.IFFT(),  # inverse FFT to convert frequency based spectrum to time domain.\n        sp.apodization.Exponential(FWHM=\"50 Hz\"),  # apodization of time domain signal.\n        sp.FFT(),  # forward FFT to convert time domain signal to frequency spectrum.\n        sp.Scale(factor=500),  # scale the frequency spectrum.\n    ]\n)\nprocessed_data = processor.apply_operations(data=sim.methods[0].simulation).real\n\n# Plot of the guess Spectrum\n# --------------------------\nplt.figure(figsize=(4.25, 3.0))\nax = plt.subplot(projection=\"csdm\")\nax.plot(experiment, \"k\", linewidth=1, label=\"Experiment\")\nax.plot(processed_data, \"r\", alpha=0.75, linewidth=1, label=\"guess spectrum\")\nax.invert_xaxis()\nplt.grid()\nplt.legend()\nplt.tight_layout()\nplt.show()"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Least-squares minimization with LMFIT\nUse the :func:`~mrsimulator.utils.spectral_fitting.make_LMFIT_params` for a quick\nsetup of the fitting parameters.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "params = sf.make_LMFIT_params(sim, processor, include={\"rotor_frequency\"})\n\nparams.pop(\"sys_0_abundance\")\nparams.pop(\"sys_1_abundance\")\nparams.pop(\"sys_2_abundance\")\nparams[\"sys_0_site_0_shielding_symmetric_eta\"].vary = False\nprint(params.pretty_print(columns=[\"value\", \"min\", \"max\", \"vary\", \"expr\"]))"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "**Solve the minimizer using LMFIT**\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "minner = Minimizer(sf.LMFIT_min_function, params, fcn_args=(sim, processor, sigma))\nresult = minner.minimize()\nresult"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## The best fit solution\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "best_fit = sf.bestfit(sim, processor)[0]\nresiduals = sf.residuals(sim, processor)[0]\n\n# Plot the spectrum\nplt.figure(figsize=(4.25, 3.0))\nax = plt.subplot(projection=\"csdm\")\nax.plot(experiment, \"k\", linewidth=1, label=\"Experiment\")\nax.plot(best_fit, \"r\", alpha=0.75, linewidth=1, label=\"Best Fit\")\nax.plot(residuals, alpha=0.75, linewidth=1, label=\"Residuals\")\nax.invert_xaxis()\nplt.xlabel(\"$^{29}$Si frequency / ppm\")\nplt.grid()\nplt.legend()\nplt.tight_layout()\nplt.show()"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Submitting data to MPContribs\n\nTo contribute to MPContribs, we need to export the mrsimulator objects to a list of\nmp-compatible data dictionaries. At present, MPContribs only support data contribution\non a per NMR site basis and, therefore, we only generate mp contributions for\nuncoupled spin systems. Use the ``mrsimulator.contribs`` module to create data\ndictionaries as follows.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "from mrsimulator.contribs import mpcontribs_export\nfrom pprint import pprint\n\nmp_project = \"lsdi_nmr_exp_test\"  # this should be your mpcontribs project name\ncards = mpcontribs_export(\n    sim,\n    [processor],\n    project=mp_project,\n    identifier=\"Ca6Si6O17(OH)2\",\n    exp_dict={\n        \"90degreePulseLength\": \"6 \u00b5s\",\n        \"relaxationDelay\": \"8 s\",\n        \"numberOfScans\": 7224,\n        \"referenceCompound\": \"TMS\",\n    },\n)\nprint(\"Number of contributions\", len(cards))\npprint(cards[0][\"data\"])"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Here, ``cards`` hold a list of mp-data dictionaries. In this example, it corresponds\nto three---the number of uncoupled spin systems.\nTo submit contributions, use the mpcontribs client as shown below.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "# from mpcontribs.client import Client\n#\n# client = Client(<YOUR-API-KEY>)  # uses MPCONTRIBS_API_KEY envvar.\n# client.submit_contributions(cards)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        ".. [#f1] Hansen, M. R., Jakobsen, H. J., Skibsted, J., $^{29}\\text{Si}$\n      Chemical Shift Anisotropies in Calcium Silicates from High-Field\n      $^{29}\\text{Si}$ MAS NMR Spectroscopy, Inorg. Chem. 2003,\n      **42**, *7*, 2368-2377.\n      `DOI: 10.1021/ic020647f <https://doi.org/10.1021/ic020647f>`_\n\n"
+      ]
+    }
+  ],
+  "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.10"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 0
+}

environment-dev.yml

@@ -5,7 +5,7 @@ channels:
 dependencies:
   - fftw>=3.3.0
   - openblas
-  - numpy>=1.17
+  - numpy>=1.20
   - nomkl
   - setuptools>=27.3
   - cython>=0.29
@@ -36,3 +36,4 @@ dependencies:
       - recommonmark
       - sphinx-version-warning
       - plotly
+      - mpcontribs-client

environment.yml

@@ -22,3 +22,4 @@ dependencies:
       - lmfit>=1.0.2
       - psutil>=5.4.8
       - plotly
+      - mpcontribs-client