Improves tutorials section and adds quick-start tutorial

Author: AndrewSazonov

docs/mkdocs.yml

@@ -54,10 +54,11 @@ nav:
         - Analysis: usage/workflow-steps/analysis.md
         - Summary: usage/workflow-steps/summary.md
   - Tutorials:
-      - Getting Started: tutorials/index.md
-      - Basic vs. Advanced:
-          - LBCO pd-neut-cwl: tutorials/basic_single-fit_pd-neut-cwl_LBCO-HRPT.ipynb
-          - PbSO4 pd-neut-xray-cwl: tutorials/advanced_joint-fit_pd-neut-xray-cwl_PbSO4.ipynb
+      - Tutorials: tutorials/index.md
+      - Getting Started:
+          - LBCO quick: tutorials/quick_single-fit_pd-neut-cwl_LBCO-HRPT.ipynb
+          - LBCO basic: tutorials/basic_single-fit_pd-neut-cwl_LBCO-HRPT.ipynb
+          - PbSO4 advanced: tutorials/advanced_joint-fit_pd-neut-xray-cwl_PbSO4.ipynb
       - Structure Refinement:
           - HS pd-neut-cwl: tutorials/cryst-struct_pd-neut-cwl_HS-HRPT.ipynb
           - Si pd-neut-tof: tutorials/cryst-struct_pd-neut-tof_Si-SEPD.ipynb

docs/tutorials/index.md

@@ -4,50 +4,60 @@ icon: material/school
 
 # :material-school: Tutorials
 
-This section offers a collection of **Jupyter Notebook examples** illustrating
-the usage of EasyDiffraction for various tasks. These tutorials act as
-**step-by-step guides**, helping users grasp the workflow of diffraction data
-analysis within EasyDiffraction.
+This section presents a collection of **Jupyter Notebook** tutorials that 
+demonstrate how to use EasyDiffraction for various tasks. These tutorials serve
+as **step-by-step guides** to help users grasp the workflow of diffraction data
+analysis using EasyDiffraction.
 
-An instruction on how to run the tutorials is provided in the
+Instructions on how to run the tutorials are provided in the
 [:material-cog-box: Installation & Setup](../installation/index.md#running-tutorials)
 section of the documentation.
 
-The tutorials are categorized as follows.
+The tutorials are organized into the following categories.
 
-## Basic vs. Advanced
+## Getting Started
 
-- [LBCO `pd-neut-cwl`](basic_single-fit_pd-neut-cwl_LBCO-HRPT.ipynb) -
-  Demonstrates usage of the EasyDiffraction API in a simplified,
+- [LBCO `quick`](quick_single-fit_pd-neut-cwl_LBCO-HRPT.ipynb) -
+  A minimal example intended as a quick reference for users already familiar 
+  with the EasyDiffraction API or who want to see an example refinement in 
+  code. This tutorial covers a Rietveld refinement of the La0.5Ba0.5CoO3 
+  crystal structure using constant wavelength neutron powder diffraction data 
+  from HRPT at PSI.
+- [LBCO `basic`](basic_single-fit_pd-neut-cwl_LBCO-HRPT.ipynb) -
+  Demonstrates the use of the EasyDiffraction API in a simplified, 
   user-friendly manner that closely follows the GUI workflow for a Rietveld
-  refinement of La0.5Ba0.5CoO3 crystal structure using constant wavelength
-  neutron powder diffraction data from HRPT at PSI.
-- [PbSO4 `pd-neut-xray-cwl`](advanced_joint-fit_pd-neut-xray-cwl_PbSO4.ipynb) -
-  Demonstrates a more flexible and advanced approach to use the
-  EasyDiffraction library, intended for users more comfortable with Python
-  programming. This tutorial covers a Rietveld refinement of PbSO4 crystal
-  structure based on the joint fit of both X-ray and neutron diffraction data.
+  refinement of the La0.5Ba0.5CoO3 crystal structure using constant wavelength
+  neutron powder diffraction data from HRPT at PSI. This tutorial provides a 
+  full explanation of the workflow with detailed comments and descriptions of 
+  every step, making it suitable for users who are new to EasyDiffraction or 
+  those who prefer a more guided approach.
+- [PbSO4 `advanced`](advanced_joint-fit_pd-neut-xray-cwl_PbSO4.ipynb) -
+  Demonstrates a more flexible and advanced approach to using the
+  EasyDiffraction library, intended for users who are more comfortable with 
+  Python programming. This tutorial covers a Rietveld refinement of the PbSO4 
+  crystal structure based on the joint fit of both X-ray and neutron 
+  diffraction data.
 
 ## Standard Diffraction
 
 - [HS `pd-neut-cwl`](cryst-struct_pd-neut-cwl_HS-HRPT.ipynb) -
-  Demonstrates a Rietveld refinement of HS crystal structure using constant
+  Demonstrates a Rietveld refinement of the HS crystal structure using constant
   wavelength neutron powder diffraction data from HRPT at PSI.
 - [Si `pd-neut-tof`](cryst-struct_pd-neut-tof_Si-SEPD.ipynb) -
-  Demonstrates a Rietveld refinement of Si crystal structure using
+  Demonstrates a Rietveld refinement of the Si crystal structure using
   time-of-flight neutron powder diffraction data from SEPD at Argonne.
 - [NCAF `pd-neut-tof`](cryst-struct_pd-neut-tof_NCAF-WISH.ipynb) -
-  Demonstrates a Rietveld refinement of Na2Ca3Al2F14 crystal structure using
-  time-of-flight neutron powder diffraction data from WISH at ISIS.
+  Demonstrates a Rietveld refinement of the Na2Ca3Al2F14 crystal structure 
+  using time-of-flight neutron powder diffraction data from WISH at ISIS.
 
 ## Pair Distribution Function (PDF)
 
 - [Ni `pd-neut-cwl`](pdf_pd-neut-cwl_Ni.ipynb) -
-  Demonstrates a PDF analysis of Ni based on data collected from a constant
+  Demonstrates a PDF analysis of Ni using data collected from a constant
   wavelength neutron powder diffraction experiment.
 - [Si `pd-neut-tof`](pdf_pd-neut-tof_Si-NOMAD.ipynb) -
-  Demonstrates a PDF analysis of Si based on data collected from a
+  Demonstrates a PDF analysis of Si using data collected from a
   time-of-flight neutron powder diffraction experiment at NOMAD at SNS.
 - [NaCl `pd-xray`](pdf_pd-xray_NaCl.ipynb) -
-  Demonstrates a PDF analysis of NaCl based on data collected from an X-ray
+  Demonstrates a PDF analysis of NaCl using data collected from an X-ray
   powder diffraction experiment.

docs/usage/workflow-steps/index.md

@@ -17,17 +17,19 @@ flowchart LR
 ```
 
 - [:material-archive: Project](project.md) - Establish a **project** as a
-  container for data, settings, and analysis results.
-- [:material-puzzle: Model](model.md) - Load an existing
+  container for sample model and experiment parameters, measured and calculated
+  data, analysis settings and results.
+- [:material-puzzle: Sample Model](model.md) - Load an existing
   **crystallographic model** in CIF format or define a new one from scratch.
 - [:material-microscope: Experiment](experiment.md) - Import
-  **experimental diffraction data** and configure **instrumental parameters**.
+  **experimental diffraction data** and configure **instrumental** and other 
+  relevant parameters.
 - [:material-calculator: Analysis](analysis.md) - Calculate the
   **diffraction pattern** and optimize the structural model by refining
   parameters to match experimental measurements.
 - [:material-clipboard-text: Summary](summary.md) - Generate a
-  **detailed report** summarizing the results of the analysis, including
-  refined parameters and visualizations.
+  **report** summarizing the results of the analysis, including
+  refined parameters.
 
 Each step is described in detail in its respective section, guiding users
 through the **entire diffraction data analysis workflow** in

docs/usage/workflow-steps/model.md

@@ -11,7 +11,7 @@ the **experimental data** to analyze and refine the structural parameters.
 EasyDiffraction allows you to:
 
 - **Manually define** a new model by specifying crystallographic parameters.
-- **Load an existing model** from a **CIF file**.
+- **Load an existing model** from a file (**CIF** format).
 
 Below, you will find instructions on how to define and manage crystallographic
 models in EasyDiffraction. It is assumed that you have already created a 

docs/usage/workflow-steps/project.md

@@ -8,21 +8,21 @@ The **Project** serves as a container for all data and metadata associated with
 a diffraction experiment. It acts as the top-level entity in EasyDiffraction,
 ensuring structured organization and easy access to relevant information. Each
 project can contain multiple **experimental datasets**, with each dataset
-containing contribution from multiple **physical models**.
+containing contribution from multiple **sample models**.
 
 EasyDiffraction allows you to:
 
 - **Manually create** a new project.
-- **Load an existing project** from **CIF files**.
+- **Load an existing project** (**CIF** format).
 
 Below, you will find instructions on how to set project in EasyDiffraction. 
 It is assumed that you have already imported the `easydiffraction` package, as 
-described in the [Getting started](../getting-started.md) section.
+described in the [Getting Started](../getting-started.md) section.
 
 ## Creating a Project Manually
 
-You can manually create a new project and specify its **title** and 
-**description**.
+You can manually create a new project and specify its short **name**, **title** 
+and **description**. All these parameters are optional.
 
 ```python
 # Create a new project
@@ -41,7 +41,7 @@ HRPT diffractometer (PSI).'''
 Saving the initial project requires specifying the directory path:
 
 ```python
-project.save_as(dir_path='lbco_hrpt', temporary=True)
+project.save_as(dir_path='lbco_hrpt')
 ```
 
 If working in the interactive mode, you can also save the project after every
@@ -67,22 +67,19 @@ project.load_from_file('data/lbco_hrpt.cif')
 The example below illustrates a typical **project structure** for a
 **constant-wavelength powder neutron diffraction** experiment:
 
-Each file within the **Project** directory plays a crucial role in defining,
-analyzing, and refining diffraction experiments.
-
 <!-- prettier-ignore-start -->
 
 <div class="cif">
 <pre>
 📁 <span class="red"><b>La0.5Ba0.5CoO3</b></span>     - Project directory.
 ├── 📄 <span class="orange"><b>project.cif</b></span>    - Main project description file.
-├── 📁 models         - Folder with individual crystallographic phases.
-│   ├── 📄 <span class="orange"><b>lbco.cif</b></span>   - File with La0.5Ba0.5CoO3 phase parameters.
+├── 📁 sample_models  - Folder with sample models (crystallographic structures).
+│   ├── 📄 <span class="orange"><b>lbco.cif</b></span>   - File with La0.5Ba0.5CoO3 structure parameters.
 │   └── ...
 ├── 📁 experiments    - Folder with instrumental parameters and measured data.
-│   ├── 📄 <span class="orange"><b>hrpt.cif</b></span>   - Measured data from HRPT@PSI & instrumental parameters.
+│   ├── 📄 <span class="orange"><b>hrpt.cif</b></span>   - Instrumental parameters and measured data from HRPT@PSI.
 │   └── ...
-├── 📄 <span class="orange"><b>analysis.cif</b></span>   - Settings for data analysis.
+├── 📄 <span class="orange"><b>analysis.cif</b></span>   - Settings for data analysis (calculator, minimizer, etc.).
 └── 📁 summary
     └── 📄 report.cif - Summary report after structure refinement.
 </pre>
@@ -96,19 +93,20 @@ Below is a detailed breakdown of the content within each project file.
 
 ### <span class="orange">project.cif</span>
 
-This file provides an overview of the project, linking relevant **models** and
-**experimental datasets**.
+This file provides an overview of the project, including **sample models** and
+**experiments** associated with the project.
 
 <!-- prettier-ignore-start -->
 
 <div class="cif">
 <pre>
 data_<span class="red"><b>La0.5Ba0.5CoO3</b></span>
 
+<span class="blue"><b>_project</b>.title</span>       "La0.5Ba0.5CoO3 from neutron diffraction at HRPT@PSI"
 <span class="blue"><b>_project</b>.description</span> "neutrons, powder, constant wavelength, HRPT@PSI"
 
 loop_
-<span class="green"><b>_model</b>.cif_file_name</span>
+<span class="green"><b>_sample_model</b>.cif_file_name</span>
 lbco.cif
 
 loop_
@@ -119,7 +117,7 @@ hrpt.cif
 
 <!-- prettier-ignore-end -->
 
-### models / <span class="orange">lbco.cif</span>
+### sample_models / <span class="orange">lbco.cif</span>
 
 This file contains crystallographic information, including **space group**,
 **unit cell parameters**, and **atomic positions**.

tutorials/quick_single-fit_pd-neut-cwl_LBCO-HRPT.py

@@ -0,0 +1,143 @@
+# %% [markdown]
+# # Structure Refinement: LBCO, HRPT
+#
+# This minimalistic example is designed to be as compact as possible for a
+# Rietveld refinement of a crystal structure using constant-wavelength neutron
+# powder diffraction data for La0.5Ba0.5CoO3 from HRPT at PSI.
+#
+# It does not contain any advanced features or options, and includes no
+# comments or explanations—these can be found in the other tutorials.
+# Default values are used for all parameters if not specified. Only essential
+# and self-explanatory code is provided.
+#
+# The example is intended for users who are already familiar with the
+# EasyDiffraction library and want to quickly get started with a simple
+# refinement. It is also useful for those who want to see what a refinement
+# might look like in code. For a more detailed explanation of the code, please
+# refer to the other tutorials.
+
+# %%
+import easydiffraction as ed
+
+# %% [markdown]
+# ## Step 1: Project
+
+# %%
+project = ed.Project()
+
+# %%
+project.plotter.engine = 'plotly'
+
+# %% [markdown]
+# ## Step 2: Sample Model
+
+# %%
+project.sample_models.add(name='lbco')
+
+# %%
+project.sample_models['lbco'].space_group.name_h_m = 'P m -3 m'
+project.sample_models['lbco'].space_group.it_coordinate_system_code = '1'
+
+# %%
+project.sample_models['lbco'].cell.length_a = 3.88
+
+# %%
+project.sample_models['lbco'].atom_sites.add(label='La',
+                                             type_symbol='La',
+                                             fract_x=0,
+                                             fract_y=0,
+                                             fract_z=0,
+                                             wyckoff_letter='a',
+                                             b_iso=0.5,
+                                             occupancy=0.5)
+project.sample_models['lbco'].atom_sites.add(label='Ba',
+                                             type_symbol='Ba',
+                                             fract_x=0,
+                                             fract_y=0,
+                                             fract_z=0,
+                                             wyckoff_letter='a',
+                                             b_iso=0.5,
+                                             occupancy=0.5)
+project.sample_models['lbco'].atom_sites.add(label='Co',
+                                             type_symbol='Co',
+                                             fract_x=0.5,
+                                             fract_y=0.5,
+                                             fract_z=0.5,
+                                             wyckoff_letter='b',
+                                             b_iso=0.5)
+project.sample_models['lbco'].atom_sites.add(label='O',
+                                             type_symbol='O',
+                                             fract_x=0,
+                                             fract_y=0.5,
+                                             fract_z=0.5,
+                                             wyckoff_letter='c',
+                                             b_iso=0.5)
+
+# %% [markdown]
+# ## Step 3: Experiment
+
+# %%
+ed.download_from_repository('hrpt_lbco.xye',
+                            branch='docs',
+                            destination='data')
+
+# %%
+project.experiments.add(name='hrpt',
+                        sample_form='powder',
+                        beam_mode='constant wavelength',
+                        radiation_probe='neutron',
+                        data_path='data/hrpt_lbco.xye')
+
+# %%
+project.experiments['hrpt'].instrument.setup_wavelength = 1.494
+project.experiments['hrpt'].instrument.calib_twotheta_offset = 0.6
+
+# %%
+project.experiments['hrpt'].peak.broad_gauss_u = 0.1
+project.experiments['hrpt'].peak.broad_gauss_v = -0.1
+project.experiments['hrpt'].peak.broad_gauss_w = 0.1
+project.experiments['hrpt'].peak.broad_lorentz_x = 0
+project.experiments['hrpt'].peak.broad_lorentz_y = 0.1
+
+# %%
+project.experiments['hrpt'].background.add(x=10, y=170)
+project.experiments['hrpt'].background.add(x=30, y=170)
+project.experiments['hrpt'].background.add(x=50, y=170)
+project.experiments['hrpt'].background.add(x=110, y=170)
+project.experiments['hrpt'].background.add(x=165, y=170)
+
+# %%
+project.experiments['hrpt'].linked_phases.add(id='lbco', scale=10.0)
+
+# %% [markdown]
+# ## Step 4: Analysis
+
+# %%
+project.sample_models['lbco'].cell.length_a.free = True
+
+project.sample_models['lbco'].atom_sites['La'].b_iso.free = True
+project.sample_models['lbco'].atom_sites['Ba'].b_iso.free = True
+project.sample_models['lbco'].atom_sites['Co'].b_iso.free = True
+project.sample_models['lbco'].atom_sites['O'].b_iso.free = True
+
+# %%
+project.experiments['hrpt'].linked_phases['lbco'].scale.free = True
+
+project.experiments['hrpt'].instrument.calib_twotheta_offset.free = True
+
+project.experiments['hrpt'].background['10'].y.free = True
+project.experiments['hrpt'].background['30'].y.free = True
+project.experiments['hrpt'].background['50'].y.free = True
+project.experiments['hrpt'].background['110'].y.free = True
+project.experiments['hrpt'].background['165'].y.free = True
+
+project.experiments['hrpt'].peak.broad_gauss_u.free = True
+project.experiments['hrpt'].peak.broad_gauss_v.free = True
+project.experiments['hrpt'].peak.broad_gauss_w.free = True
+project.experiments['hrpt'].peak.broad_lorentz_y.free = True
+
+# %%
+project.analysis.fit()
+
+# %%
+project.plot_meas_vs_calc(expt_name='hrpt', show_residual=True)