Merge pull request #27 from DeepanshS/czjzek

Finalize v0.4 release (updates to Czjzek model)

CHANGELOG

@@ -1,12 +1,14 @@
 
-Upcoming additions and changes
-------------------------------
+v0.4.0
+------
 
 What's new!
 '''''''''''
 
-- Czjzek and extended Czjzek second-rank symmetric tensor distribution models.
-- A new utility function, ``single_site_system_generator``, for generating a list of
+- ⭐ Improved simulation performance. ⭐ See our :ref:`benchmark`.
+- Added Czjzek and extended Czjzek second-rank symmetric tensor distribution models
+  for creating spin systems for amorphous materials.
+- Add a new utility function, ``single_site_system_generator``, for generating a list of
   single-site spin systems from a 1D list/array of respective tensor parameters.
 
 v0.3.0

README.md

@@ -28,14 +28,18 @@ of the `mrsimulator` library is written in C, wrapped, and made available in pyt
 - Packages using mrsimulator -
   - [mrinversion](https://mrinversion.readthedocs.io/en/latest/)
 
+> **View our example gallery**
+>
+> [![](https://img.shields.io/badge/View-Example%20Gallery-Purple?s=small)](https://mrsimulator.readthedocs.io/en/latest/auto_examples/index.html)
+
 ### Features
 
 The `mrsimulator` package currently offers the following
 
 - **Fast simulation** of one-dimensional solid-state NMR spectra. See our
   [benchmark results](https://mrsimulator.readthedocs.io/en/latest/benchmark.html).
 
-- **Uncoupled spin system**
+- Simulation of **uncoupled spin system**
 
   - for spin I=1/2, and quadrupole I>1/2 nuclei,
   - at arbitrary macroscopic magnetic flux density,
@@ -47,6 +51,11 @@ The `mrsimulator` package currently offers the following
   - 1D Bloch decay spectrum, and
   - 1D Bloch decay central transition spectrum.
 
+- **Models** for tensor parameter distribution in amorphous materials.
+
+  - Czjzek
+  - Extendend Czjzek
+
 ### Goals for the near future
 
 Our current objectives for the future are the following
@@ -68,10 +77,6 @@ Our current objectives for the future are the following
 For more information, refer to the
 [documentation](https://mrsimulator.readthedocs.io/en/latest/).
 
-> **View our example gallery**
->
-> [![](https://img.shields.io/badge/View-Example%20Gallery-Purple?s=small)](https://mrsimulator.readthedocs.io/en/latest/auto_examples/index.html)
-
 ## Installation
 
     $ pip install mrsimulator

docs/_static/style.css

@@ -221,10 +221,6 @@ table caption:hover {
   padding-right: 1.5em; */
 }
 
-.sidebar .logo img {
-  filter: invert(1) brightness(1.75);
-}
-
 /* searchbar */
 #searchbox > h3,
 #searchbox > p {
@@ -384,10 +380,12 @@ footer .flex {
 footer .flex a {
   text-decoration: none;
 }
-footer a {
+footer a,
+footer a:visited {
   color: rgb(255, 166, 94);
 }
-footer a:hover {
+footer a:hover,
+footer a:active {
   color: rgb(255, 205, 164);
 }
 

docs/benchmark.rst

@@ -11,32 +11,34 @@ The following benchmark shows the performance of the library in computing the
 solid-state NMR spectra from single-site spin systems for the shift and
 quadrupolar tensor interactions at static and MAS conditions.
 
-**Computational specs**
 
-A benchmark for the number of single-site spin systems computer per second.
-Higher is better.
 
-.. figure:: _static/benchmark_sites.*
+.. A benchmark for the number of single-site spin systems computer per second.
+
+.. figure:: _static/benchmark.*
     :figclass: figure
 
-    The number of single-site spin systems computer per seconds.
+    (Left) The number of single-site spin systems computer per seconds. (Right)
+    The execution time (in ms) in computing spectrum from a single-site spin system.
 
 
-A similar benchmark showing the execution time of a single-site spin system. Lower
-is better.
+.. A similar benchmark showing the execution time of a single-site spin system. Lower
+.. is better.
 
-.. figure:: _static/benchmark_time.*
-    :figclass: figure
+.. .. figure:: _static/benchmark_time.*
+..     :figclass: figure
 
-    The execution time (in ms) in computing spectrum from a single-site spin system.
+..     The execution time (in ms) in computing spectrum from a single-site spin system.
+
+**Benchmark specs**
 
 The benchmarks were performed on a 2.3 GHz Quad-Core Intel Core i5 Laptop using 8
 GB 2133 MHz LPDDR3 memory. For consistent benchmarking, 1000 single-site
 spin systems were constructed, where the tensor parameters of the sites (`zeta`
 and `eta` for the shielding tensor, and `Cq` and `eta` for the quadrupolar
-tensor) were randomly populated. The execution time for this setup was
-recorded, and the process repeated 70 times, giving a mean and a standard
-deviation.
+tensor) were randomly populated. The execution time for this setup was recorded.
+and the process repeated 70 times. The reported value is the mean and the
+standard deviation.
 
 All calculations were performed using the default Simulator
 :attr:`~mrsimulator.Simulator.config` attribute values.

docs/index.rst

@@ -97,38 +97,44 @@ the ``mrsimulator`` library is written in C, wrapped, and made available in pyth
 
 ----
 
+.. only:: html
+
+    .. raw:: html
+
+        <br>
+
+    **View our example gallery**
+
+    .. image:: https://img.shields.io/badge/View-Example%20Gallery-Purple?s=small
+        :target: auto_examples/index.html
+
+----
+
 **Features**
 
 The ``mrsimulator`` package currently offers the following
 
 - **Fast simulation** of one-dimensional solid-state NMR spectra. See our :ref:`benchmark` results.
 
-- Uncoupled spin system
+- Simulation of **uncoupled spin system**
     - for spin :math:`I=\frac{1}{2}`, and quadrupole :math:`I \ge \frac{1}{2}` nuclei,
     - at arbitrary macroscopic magnetic flux density,
     - at arbitrary rotor angles, and
     - at arbitrary spinning frequency.
 
-- The library includes the following NMR methods,
+- The library includes the following **NMR methods**,
     - 1D Bloch decay spectrum, and
     - 1D Bloch decay central transition spectrum.
 
-.. only:: html
-
-    .. raw:: html
-
-        <br>
-
-    **View our example gallery**
-
-    .. image:: https://img.shields.io/badge/View-Example%20Gallery-Purple?s=small
-        :target: auto_examples/index.html
+- **Models** for tensor parameter distribution in amorphous materials.
+    - Czjzek
+    - Extendend Czjzek
 
 ----
 
 **Goals for the near future**
 
-Our current objectives for the future are the following
+Our current objectives are the following
 
 - Include spectral simulation of coupled spin systems for
     - spin :math:`I=\frac{1}{2}`, and quadrupole :math:`I \ge \frac{1}{2}` nuclei,

docs/model/czjzek.rst

@@ -36,10 +36,11 @@ function. Let's first draw points from this distribution, using the
     :context: close-figs
     :include-source:
 
-    >>> zeta_dist, eta_dist = cz_model.rvs(n=50000)
+    >>> zeta_dist, eta_dist = cz_model.rvs(size=50000)
 
-In the above example, we draw `n=50000` random points of the distribution. The output
-``zeta_dist`` and ``eta_dist`` hold the coordinates of the points.
+In the above example, we draw `size=50000` random points of the distribution. The output
+``zeta_dist`` and ``eta_dist`` hold the tensor parameter coordinates of the points, defined
+in the Haeberlen convention.
 The scatter plot of these coordinates is shown below.
 
 .. plot::

docs/model/extended_czjzek.rst

@@ -4,13 +4,13 @@ Extended Czjzek distribution
 ----------------------------
 
 An Extended Czjzek distribution model is a random perturbation of the second-rank
-traceless symmetric tensors about a non-zero tensor. See :ref:`czjzek_model` and
+traceless symmetric tensors about a non-zero tensor. See :ref:`ext_czjzek_model` and
 references within for a brief description of the model.
 
 Extendend Czjzek distribution of symmetric shielding tensors
 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 
-To generate an extendend Czjzek distribution, use the
+To generate an extended Czjzek distribution, use the
 :class:`~mrsimulator.models.ExtCzjzekDistribution` class as follows.
 
 .. plot::
@@ -41,10 +41,11 @@ the :meth:`~mrsimulator.models.ExtCzjzekDistribution.rvs` method of the instance
     :context: close-figs
     :include-source:
 
-    >>> zeta_dist, eta_dist = shielding_model.rvs(n=50000)
+    >>> zeta_dist, eta_dist = shielding_model.rvs(size=50000)
 
-In the above example, we draw `n=50000` random points of the distribution. The output
-``zeta_dist`` and ``eta_dist`` hold the coordinates of the points.
+In the above example, we draw `size=50000` random points of the distribution. The output
+``zeta_dist`` and ``eta_dist`` hold the tensor parameter coordinates of the points, defined
+in the Haeberlen convention.
 The scatter plot of these coordinates is shown below.
 
 .. plot::

docs/theory/models.rst

@@ -87,6 +87,7 @@ and the explicit matrix form the :math:`{\bf S}` is
 In a shorthand notation, we denote a Czjzek distribution of second-rank traceless
 symmetric tensor as :math:`S_C(\sigma)`.
 
+.. _ext_czjzek_model:
 
 Extended Czjzek distribution
 ----------------------------

examples/1D_simulation/README.rst

@@ -3,4 +3,6 @@
 -----------------
 
 The following examples are the NMR spectrum simulation of a Bloch decay and Bloch decay
-central transition signal.
+central transition selective signal for crystalline and amorphous materials. For NMR of
+amorphous solids, we show examples of how to simulate spectrum using your model or using
+commonly used models such as Czjzek or extended Czjzek.

examples/1D_simulation/plot_5_czjzek_distribution.py

@@ -60,20 +60,12 @@
 # :math:`\eta` parameters, use the
 # :func:`~mrsimulator.utils.collection.single_site_system_generator` utility function.
 systems = single_site_system_generator(
-    isotopes="13C",
-    shielding_symmetric={"zeta": z_dist.ravel(), "eta": e_dist.ravel()},
-    abundance=amp.ravel(),
+    isotopes="13C", shielding_symmetric={"zeta": z_dist, "eta": e_dist}, abundance=amp,
 )
 
 # %%
-# Here, the variable ``systems`` hold an array of single-site spin systems. Note, the
-# original :math:`\zeta`-:math:`\eta` grid (100 x 21) should produce 2100 spin systems.
-# The resulting number of spin systems from the above method is, however, less than
-# the expected number. The spin systems with zero abundance are dropped.
-print(len(systems))
-
-# %%
-# Create a simulator object and add the above system and a method.
+# Here, the variable ``systems`` hold an array of single-site spin systems.
+# Next, create a simulator object and add the above system and a method.
 sim = Simulator()
 sim.spin_systems = systems  # add the systems
 sim.methods = [BlochDecaySpectrum(channels=["13C"])]  # add the method
@@ -116,9 +108,7 @@
 #
 # Create the spin systems.
 systems = single_site_system_generator(
-    isotopes="71Ga",
-    quadrupolar={"Cq": cq_dist.ravel() * 1e6, "eta": e_dist.ravel()},
-    abundance=amp.ravel(),
+    isotopes="71Ga", quadrupolar={"Cq": cq_dist * 1e6, "eta": e_dist}, abundance=amp,
 )
 
 # %%

examples/1D_simulation/plot_6_extended_czjzek.py

@@ -55,9 +55,7 @@
 #
 # Create the spin systems from the above :math:`\zeta` and :math:`\eta` parameters.
 systems = single_site_system_generator(
-    isotopes="13C",
-    shielding_symmetric={"zeta": z_dist.ravel(), "eta": e_dist.ravel()},
-    abundance=amp.ravel(),
+    isotopes="13C", shielding_symmetric={"zeta": z_dist, "eta": e_dist}, abundance=amp,
 )
 print(len(systems))
 
@@ -110,9 +108,7 @@
 # **Static spectrum**
 # Create the spin systems.
 systems = single_site_system_generator(
-    isotopes="71Ga",
-    quadrupolar={"Cq": cq_dist.ravel() * 1e6, "eta": e_dist.ravel()},
-    abundance=amp.ravel(),
+    isotopes="71Ga", quadrupolar={"Cq": cq_dist * 1e6, "eta": e_dist}, abundance=amp,
 )
 
 # %%