diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml new file mode 100644 index 0000000..affe5c0 --- /dev/null +++ b/.github/workflows/build-docs.yml @@ -0,0 +1,221 @@ +name: Build and deploy docs + +on: + # Trigger the workflow on push + push: + # To the develop and master branches + branches: [develop, master] + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +env: + # Set the environment variables to be used in all jobs defined in this workflow + # Set the CI_BRANCH environment variable to be the branch name + # NOTE: Use the same branch name as the one of easyscience/diffraction-lib. This is + # required to download the Jupyter notebooks from the easyscience/diffraction-lib repository + # Set the NOTEBOOKS_DIR environment variable to be the directory containing the Jupyter notebooks + CI_BRANCH: ${{ github.head_ref || github.ref_name }} + NOTEBOOKS_DIR: examples + +jobs: + # Job 1: Build the static files for the documentation site + build-docs: + runs-on: macos-14 # Use macOS to switch to dark mode for Plotly charts + + steps: + - name: Cancel previous workflow runs + uses: n1hility/cancel-previous-runs@v2 + with: + token: ${{ secrets.GITHUB_TOKEN }} + + # Without this step, GITHUB_REPOSITORY is not accessible from mkdocs.yml + - name: Get GitHub repository + run: echo "GITHUB_REPOSITORY=$GITHUB_REPOSITORY" >> $GITHUB_ENV + + # Save the latest release version of easyscience/diffraction-lib to RELEASE_VERSION + # RELEASE_VERSION is used in the mkdocs.yml file to set release_version. + # The release_version is then needed to display the latest release version in the index.md file + - name: Get the latest release version of EasyDiffraction Library + # This method is not working in CI with the following error: "API rate limit exceeded..." + #run: echo "RELEASE_VERSION=$(curl https://api.github.com/repos/easyscience/diffraction-lib/releases/latest | grep -i 'tag_name' | awk -F '"' '{print $4}')" >> $GITHUB_ENV + # This method is not optimal and takes some more time to run, but it works and it is reliable + run: | + git clone --depth 1 https://github.com/easyscience/EasyDiffractionLib . + git fetch --tags + echo "RELEASE_VERSION=$(git describe --tags --abbrev=0)" >> $GITHUB_ENV + + # Activate dark mode to create documentation with Plotly charts in dark mode + # Need a better solution to automatically switch the chart colour theme based on the mkdocs material switcher + # Something similar to mkdocs_plotly_plugin https://haoda-li.github.io/mkdocs-plotly-plugin/, + # but for generating documentation from notepads + - name: Activate dark mode + run: | + brew install dark-mode + dark-mode status + dark-mode on + dark-mode status + + - name: Check-out repository + uses: actions/checkout@v4 + + - name: Set up Python environment + uses: actions/setup-python@v4 + with: + python-version: '3.12' + + - name: Upgrade package installer for Python + run: python -m pip install --upgrade pip + + # Install MkDocs -- static site generator + # https://www.mkdocs.org + - name: Install MkDocs and its dependencies + run: > + pip install mkdocs mkdocs-material 'mkdocs-autorefs<1.3.0' + mkdocs-jupyter mkdocs-plugin-inline-svg + mkdocs-markdownextradata-plugin mkdocstrings-python + + # Install EasyDiffraction Library to run Jupyter notebooks + # Install with the 'charts' and 'docs' extras + - name: Install EasyDiffraction Library and its dependencies + run: pip install 'easydiffraction[charts]' + + # Download and add the extra files from the easyscience/assets-docs repository + - name: Get easyscience/assets-docs files + run: | + git clone https://github.com/easyscience/assets-docs.git + cp -R assets-docs/docs/assets/ docs/assets/ + cp -R assets-docs/includes/ includes/ + cp -R assets-docs/overrides/ overrides/ + + # Download and add the extra files from the easyscience/assets-branding repository + - name: Get easyscience/assets-branding files + run: | + git clone https://github.com/easyscience/assets-branding.git + mkdir -p docs/assets/images/ + cp assets-branding/EasyDiffraction/logos/ed-logo_dark.svg docs/assets/images/ + cp assets-branding/EasyDiffraction/logos/ed-logo_light.svg docs/assets/images/ + cp assets-branding/EasyDiffraction/logos/edl-logo_dark.svg docs/assets/images/logo_dark.svg + cp assets-branding/EasyDiffraction/logos/edl-logo_light.svg docs/assets/images/logo_light.svg + cp assets-branding/EasyDiffraction/icons/ed-icon_256x256.png docs/assets/images/favicon.png + mkdir -p overrides/.icons/ + cp assets-branding/EasyDiffraction/icons/ed-icon_bw.svg overrides/.icons/easydiffraction.svg + cp assets-branding/EasyScienceOrg/icons/eso-icon_bw.svg overrides/.icons/easyscience.svg + + # Copy Jupyter notebooks from the project to the docs folder + # The notebooks are used to generate the documentation + - name: + Copy Jupyter notebooks from ${{ env.NOTEBOOKS_DIR }}/ to docs/${{ + env.NOTEBOOKS_DIR }}/ + run: cp -R ${{ env.NOTEBOOKS_DIR }}/ docs/${{ env.NOTEBOOKS_DIR }}/ + + # The following step is needed to avoid the following message during the build: + # "Matplotlib is building the font cache; this may take a moment" + - name: Pre-build site step + run: python -c "import easydiffraction" + + # Create the mkdocs.yml configuration file + # The file is created by merging two files: + # - assets-docs/mkdocs.yml - the common configuration (theme, plugins, etc.) + # - docs/mkdocs.yml - the project-specific configuration (project name, TOC, etc.) + - name: Create mkdocs.yml file + run: cat ../assets-docs/mkdocs.yml docs/mkdocs.yml > mkdocs.yml + + # Build the static files + # Input: docs/ directory containing the Markdown files + # Output: site/ directory containing the generated HTML files + - name: Build site with MkDocs + run: | + export JUPYTER_PLATFORM_DIRS=1 + mkdocs build + + # Set up the Pages action to configure the static files to be deployed + # NOTE: The repository must have GitHub Pages enabled and configured to build using GitHub Actions + # This can be done via https://github.com/easyscience/diffraction-lib/settings/pages + # Select: Build and deploy - Source - GitHub Actions + - name: Setup GitHub Pages + uses: actions/configure-pages@v5 + + # Upload the static files from the site/ directory to be used in the next job + # This artifact is named github-pages and is a single gzip archive containing a single tar file + # The artifact is then used in the next job by actions/deploy-pages to deploy the static files to GitHub Pages + # Unfortunately, the artifact is not available for download, so extra steps below are needed to do similar things + - name: + Upload built site as artifact for + easyscience.github.io/diffraction-lib (all branches) + uses: actions/upload-pages-artifact@v3 + with: + path: site/ + + # Upload the static files from the site/ directory to be used in the next job + # This extra step is needed to allow the download of the artifact in the next job + # for pushing its content to the branch named 'easydiffraction.org' + - name: + Upload built site as artifact for gh_pages and easydiffraction.org + (master branch) + if: ${{ env.CI_BRANCH == 'master' }} + uses: actions/upload-artifact@v4 + with: + name: artifact # name of the artifact (without the extension zip) + path: site/ + if-no-files-found: 'error' + compression-level: 0 + + # Job 2: Deploy the static files + deploy-docs: + needs: build-docs # previous job 'build-docs' need to be finished first + + # Grant GITHUB_TOKEN the permissions required to make a Pages deployment + permissions: + contents: read + pages: write # to deploy to Pages + id-token: write # to verify the deployment, originates from an appropriate source + + # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. + # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. + concurrency: + group: 'pages' + cancel-in-progress: false + + # Deploy to the github-pages environment + environment: + name: github-pages # Artifact name + url: ${{ steps.deployment.outputs.page_url }} + + runs-on: ubuntu-latest + + steps: + # Deploy the static files created in the previous job to GitHub Pages + # To allow the deployment of the static files to GitHub Pages, no + # restrictions on the branch name need to be set for desired branches on + # https://github.com/easyscience/diffraction-lib/settings/environments + # Currently, only develop and master branches are allowed to deploy to GitHub Pages + # Deployed pages are available at https://easyscience.github.io/diffraction-lib + - name: Deploy to easyscience.github.io/diffraction-lib (all branches) + uses: actions/deploy-pages@v4 + + # Download built site as artifact from a previous job for gh_pages and easydiffraction.org (master branch) + - name: Download built site from previous job (master branch) + if: ${{ env.CI_BRANCH == 'master' }} + uses: actions/download-artifact@v4 + with: # name or path are taken from the upload step of the previous job + name: artifact + path: site/ # directory to extract downloaded zipped artifacts + + # Push the site files created in the previous job to the gh_pages branch + # To be able to push to the gh_pages branch, the personal GitHub API access + # token GH_API_PERSONAL_ACCSESS_TOKEN must be set for this repository via + # https://github.com/easyscience/diffraction-lib/settings/secrets/actions + # This branch is used to deploy the site to the custom domain https://easydiffraction.org + # Deploying is done with a webhook: https://github.com/easyscience/diffraction-lib/settings/hooks + # This is done for the gh_pages branch when the site is tested with a step above + - name: + Deploy to gh_pages branch to trigger deployment to easydiffraction.org + (master branch) + if: ${{ env.CI_BRANCH == 'master' }} + uses: s0/git-publish-subdir-action@develop + env: + GITHUB_TOKEN: ${{ secrets.GH_API_PERSONAL_ACCSESS_TOKEN }} + REPO: self + BRANCH: gh_pages + FOLDER: site diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index f4523df..ef24eb4 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -27,13 +27,21 @@ This is an example of a workflow that describes the development process. ```console python -m pip install --upgrade pip ``` -- Install easydiffraction from root with `dev` extras for development +- Install easydiffraction from root with `dev` extras for development, `charts` + extras for Jupyter notebooks and `docs` extras for building documentation ```console - pip install '.[dev]' + pip install '.[dev,charts,docs]' ``` - Make changes in the code + ```console + ... + ``` +- Check the validity of pyproject.toml + ```console + validate-pyproject pyproject.toml + ``` - Run Ruff - Python linter and code formatter (configuration is in - pyproject.toml) Linting (overwriting files) + pyproject.toml)
Linting (overwriting files) ```console ruff check . --fix ``` @@ -41,8 +49,8 @@ This is an example of a workflow that describes the development process. ```console ruff format . ``` -- Install and run Prettier - code formatter for markdown, YAML, TOML files - Formatting (overwriting files) +- Install and run Prettier - code formatter for Markdown, YAML, TOML, etc. files + (configuration in prettierrc.toml)
Formatting (overwriting files) ```console npm install prettier prettier-plugin-toml --save-dev --save-exact npx prettier . --write --config=prettierrc.toml @@ -51,7 +59,8 @@ This is an example of a workflow that describes the development process. ```console pytest tests/ --color=yes -n auto ``` -- Clear all Jupyter notebooks output +- Clear all Jupyter notebooks output (Only those that were changed!). Replace + `examples/*.ipynb` with the path to the notebook(s) you want to clear ```console jupyter nbconvert --clear-output --inplace examples/*.ipynb ``` @@ -61,7 +70,47 @@ This is an example of a workflow that describes the development process. ``` - Run Jupyter notebooks as tests ```console - pytest --nbmake examples/*ipynb --nbmake-timeout=300 --color=yes -n=auto + pytest --nbmake examples/ --ignore-glob='examples/*emcee*' --nbmake-timeout=300 --color=yes -n=auto + ``` +- Add extra files to build documentation (from `../assets-docs/` and + `../assets-branding/` directories) + ```console + cp -R ../assets-docs/docs/assets/ docs/assets/ + cp -R ../assets-docs/includes/ includes/ + cp -R ../assets-docs/overrides/ overrides/ + mkdir -p docs/assets/images/ + cp ../assets-branding/EasyDiffraction/logos/ed-logo_dark.svg docs/assets/images/ + cp ../assets-branding/EasyDiffraction/logos/ed-logo_light.svg docs/assets/images/ + cp ../assets-branding/EasyDiffraction/logos/edl-logo_dark.svg docs/assets/images/logo_dark.svg + cp ../assets-branding/EasyDiffraction/logos/edl-logo_light.svg docs/assets/images/logo_light.svg + cp ../assets-branding/EasyDiffraction/icons/ed-icon_256x256.png docs/assets/images/favicon.png + mkdir -p overrides/.icons/ + cp ../assets-branding/EasyDiffraction/icons/ed-icon_bw.svg overrides/.icons/easydiffraction.svg + cp ../assets-branding/EasyScienceOrg/icons/eso-icon_bw.svg overrides/.icons/easyscience.svg + cp -R examples/ docs/examples/ + cat ../assets-docs/mkdocs.yml docs/mkdocs.yml > mkdocs.yml + ``` +- Build documentation with MkDocs - static site generator + ```console + export JUPYTER_PLATFORM_DIRS=1 + mkdocs serve + ``` +- Test the documentation locally (built in the `site/` directory). E.g., on + macOS, open the site in the default browser via the terminal + ```console + open http://127.0.0.1:8000 + ``` +- Clean up after building documentation + ```console + rm -rf site/ + rm -rf docs/assets/ + rm -rf includes/ + rm -rf overrides/ + rm -rf docs/examples/ + rm -rf node_modules/ + rm mkdocs.yml + rm package-lock.json + rm package.json ``` - Commit changes ```console diff --git a/LICENSE b/LICENSE index f893b20..450a5ac 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,7 @@ BSD 3-Clause License -Copyright (c) 2024, EasyDiffractionLib contributors (https://github.com/EasyScience/EasyDiffractionLib) +Copyright (c) 2025, EasyDiffraction contributors +(https://github.com/EasyScience/EasyDiffractionLib) All rights reserved. Redistribution and use in source and binary forms, with or without diff --git a/README.md b/README.md index 19d69f6..891eab1 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,11 @@ -

+

- + - + - EasyDiffraction + EasyDiffraction

@@ -34,8 +34,7 @@ We welcome contributions! Our vision is for **EasyDiffraction** to be a community-driven, open-source project supported by a diverse group of contributors. -The project is currently maintained by the [European Spallation Source (ESS)] in -Sweden. +The project is currently maintained by the [European Spallation Source (ESS)]. If you'd like to contribute, please refer to our [Contributing Guidelines] for information about our code of conduct and instructions on submitting pull diff --git a/docs/analysis.md b/docs/analysis.md new file mode 100644 index 0000000..1bca73a --- /dev/null +++ b/docs/analysis.md @@ -0,0 +1,77 @@ +# Analysis + +This section contains information about the analysis of diffraction data in +EasyDiffraction. + +### Model-dependent analysis + +There are two general approaches to the analysis of data: **model-dependent** +and **model-independent**. In the following examples, we are going to focus on +the former. However, the latter is worth briefly highlighting. + +A model-independent approach to analysis is where no assumptions are made about +the system that is being studied and conclusions are drawn only from the data +that has been observed. However, in many applications, it is desirable to +include what we think we know about the system, and so model-dependent analysis +is used. + +Model-dependent analysis involves the development of a mathematical model that +describes the model dataset that would be found for our system. This +mathematical model usually has parameters that are linked to the physics and +chemistry of our system. These parameters are varied to optimise the model, +using an optimisation algorithm, with respect to the experimental data, i.e., to +get the best agreement between the model data and the experimental data. + +Below is a diagram illustrating this process: + +```mermaid +flowchart LR + a(Propose
model) + b(Set/change
model
parameter
values) + c(Calculate
model
data) + d(Compare
model data to
experimental
data) + e(Stop
iteration) + a --> b + b --> c + c --> d + d-- Threshold
not
reached -->b + d-- Threshold
reached -->e +``` + +Model-dependent analysis is popular in the analysis of neutron scattering data, +and we will use it in the following examples. + +## Calculation engines + +EasyDiffraction is designed to be a flexible and extensible tool for calculating +diffraction patterns. It can use different calculation engines to perform the +calculations. + +We currently rely on [CrysPy](https://www.cryspy.fr) as a calculation engine. +CrysPy is a Python library originally developed for analysing polarised neutron +diffraction data. It is now evolving into a more general purpose library and +covers powders and single crystals, nuclear and (commensurate) magnetic +structures, unpolarised neutron and X-ray diffraction. + +Another calculation engine is +[CrysFML](https://code.ill.fr/scientific-software/CrysFML2008). This library is +a collection of Fortran modules for crystallographic computations. It is used in +the software package [FullProf](https://www.ill.eu/sites/fullprof/), and we are +currently working on its integration into EasyDiffraction. + +## Minimisation engines + +EasyDiffraction uses different third-party libraries to perform the +model-dependent analysis. + +Most of the examples in this section will use the +[lmfit](https://lmfit.github.io/lmfit-py/) package, which provides a high-level +interface to non-linear optimisation and curve fitting problems for Python. It +is one of the tools that can be used to fit models to the experimental data. + +Another package that can be used for the same purpose is +[bumps](https://bumps.readthedocs.io/en/latest/). In addition to traditional +optimizers which search for the best minimum they can find in the search space, +bumps provides Bayesian uncertainty analysis which explores all viable minima +and finds confidence intervals on the parameters based on uncertainty in the +measured values. diff --git a/docs/dictionaries.md b/docs/dictionaries.md new file mode 100644 index 0000000..528c1c0 --- /dev/null +++ b/docs/dictionaries.md @@ -0,0 +1,158 @@ +# Dictionaries + +All parameter names used in EasyDiffraction are divided into several +dictionaries given below. Each keyword in the dictionaries has one badge showing +the corresponding type of dictionary, and can have one or more badges showing +the type of experiment to which the keyword belongs. + +## Crystallographic information file + +EasyDiffraction input and output files use the simple, human-readable STAR/CIF +data format, following the specifications of +[International Union of Crystallography](https://www.iucr.org) (IUCr), wherever +possible. + +## Model dictionary + +This dictionary provides data names for describing model parameters. + +[pd-neut-cwl][3]{:.label-experiment} [pd-neut-tof][3]{:.label-experiment} +[sc-neut-cwl][3]{:.label-experiment} [pd-xray][3]{:.label-experiment} + +- [\_space_group](dictionaries/_space_group.md) [coreCIF][1]{:.label-cif} + - [\_space_group.name_H-M_alt](dictionaries/_space_group.md) + [coreCIF][1]{:.label-cif} + - [\_space_group.IT_coordinate_system_code](dictionaries/_space_group.md) + [coreCIF][1]{:.label-cif} +- [\_cell](dictionaries/_cell.md) [coreCIF][1]{:.label-cif} + - [\_cell.angle_alpha](dictionaries/_cell.md) [coreCIF][1]{:.label-cif} + - [\_cell.angle_beta](dictionaries/_cell.md) [coreCIF][1]{:.label-cif} + - [\_cell.angle_gamma](dictionaries/_cell.md) [coreCIF][1]{:.label-cif} + - [\_cell.length_a](dictionaries/_cell.md) [coreCIF][1]{:.label-cif} + - [\_cell.length_b](dictionaries/_cell.md) [coreCIF][1]{:.label-cif} + - [\_cell.length_c](dictionaries/_cell.md) [coreCIF][1]{:.label-cif} +- [\_atom_site](dictionaries/_atom_site.md) [coreCIF][1]{:.label-cif} + - [\_atom_site.label](dictionaries/_atom_site.md) [coreCIF][1]{:.label-cif} + - [\_atom_site.type_symbol](dictionaries/_atom_site.md) + [coreCIF][1]{:.label-cif} + - [\_atom_site.fract_x](dictionaries/_atom_site.md) [coreCIF][1]{:.label-cif} + - [\_atom_site.fract_y](dictionaries/_atom_site.md) [coreCIF][1]{:.label-cif} + - [\_atom_site.fract_z](dictionaries/_atom_site.md) [coreCIF][1]{:.label-cif} + - [\_atom_site.occupancy](dictionaries/_atom_site.md) + [coreCIF][1]{:.label-cif} + - [\_atom_site.ADP_type](dictionaries/_atom_site.md) [coreCIF][1]{:.label-cif} + - [\_atom_site.B_iso_or_equiv](dictionaries/_atom_site.md) + [coreCIF][1]{:.label-cif} + - [\_atom_site.site_symmetry_multiplicity](dictionaries/_atom_site.md) + [coreCIF][1]{:.label-cif} + - [\_atom_site.Wyckoff_symbol](dictionaries/_atom_site.md) + [coreCIF][1]{:.label-cif} + +## Experiment and instrument dictionary + +This dictionary provides data names for describing experimental and instrumental +parameters. + +[pd-neut-cwl][3]{:.label-experiment} [pd-neut-tof][3]{:.label-experiment} +[sc-neut-cwl][3]{:.label-experiment} [pd-xray][3]{:.label-experiment} + +- [\_diffrn_radiation](dictionaries/_diffrn_radiation.md) + [coreCIF][1]{:.label-cif} + - [\_diffrn_radiation.probe](dictionaries/_diffrn_radiation.md) + [coreCIF][1]{:.label-cif} + +[pd-neut-cwl][3]{:.label-experiment} [sc-neut-cwl][3]{:.label-experiment} +[pd-xray][3]{:.label-experiment} + +- [\_diffrn_radiation_wavelength](dictionaries/_diffrn_radiation_wavelength.md) + [coreCIF][1]{:.label-cif} + - [\_diffrn_radiation_wavelength.wavelength](dictionaries/_diffrn_radiation_wavelength.md) + [coreCIF][1]{:.label-cif} +- [\_pd_background](dictionaries/_pd_background.md) [pdCIF][2]{:.label-cif} + - [\_pd_background.line_segment_X](dictionaries/_pd_background.md) + [pdCIF][2]{:.label-cif} + - [\_pd_background.line_segment_intensity](dictionaries/_pd_background.md) + [pdCIF][2]{:.label-cif} + - [\_pd_background.X_coordinate](dictionaries/_pd_background.md) + [pdCIF][2]{:.label-cif} +- [\_pd_phase_block](dictionaries/_pd_phase.md) [pdCIF][2]{:.label-cif} + - [\_pd_phase_block.id](dictionaries/_pd_phase.md) [pdCIF][2]{:.label-cif} + - [\_pd_phase_block.scale](dictionaries/_pd_phase.md) + [customCIF][0]{:.label-cif} + +[pd-neut-cwl][3]{:.label-experiment} + +- [\_pd_calib](dictionaries/_pd_calib.md) [pdCIF][2]{:.label-cif} + - [\_pd_calib.2theta_offset](dictionaries/_pd_calib.md) + [pdCIF][2]{:.label-cif} +- [\_pd_instr](dictionaries/_pd_instr.md) [pdCIF][2]{:.label-cif} + - [\_pd_instr.resolution_u](dictionaries/_pd_instr.md) + [customCIF][0]{:.label-cif} + - [\_pd_instr.resolution_v](dictionaries/_pd_instr.md) + [customCIF][0]{:.label-cif} + - [\_pd_instr.resolution_w](dictionaries/_pd_instr.md) + [customCIF][0]{:.label-cif} + - [\_pd_instr.resolution_x](dictionaries/_pd_instr.md) + [customCIF][0]{:.label-cif} + - [\_pd_instr.resolution_y](dictionaries/_pd_instr.md) + [customCIF][0]{:.label-cif} + - [\_pd_instr.reflex_asymmetry_p1](dictionaries/_pd_instr.md) + [customCIF][0]{:.label-cif} + - [\_pd_instr.reflex_asymmetry_p2](dictionaries/_pd_instr.md) + [customCIF][0]{:.label-cif} + - [\_pd_instr.reflex_asymmetry_p3](dictionaries/_pd_instr.md) + [customCIF][0]{:.label-cif} + - [\_pd_instr.reflex_asymmetry_p4](dictionaries/_pd_instr.md) + [customCIF][0]{:.label-cif} +- [\_pd_meas](dictionaries/_pd_meas.md) [pdCIF][2]{:.label-cif} + - [\_pd_meas.2theta_scan](dictionaries/_pd_meas.md) [pdCIF][2]{:.label-cif} + - [\_pd_meas.intensity_total](dictionaries/_pd_meas.md) + [pdCIF][2]{:.label-cif} + - [\_pd_meas.intensity_total_su](dictionaries/_pd_meas.md) + [pdCIF][2]{:.label-cif} + +[pd-neut-tof][3]{:.label-experiment} + +- [\_pd_instr](dictionaries/_pd_instr.md) [pdCIF][2]{:.label-cif} + - [\_pd_instr.zero](dictionaries/_pd_instr.md) [customCIF][0]{:.label-cif} + - [\_pd_instr.dtt1](dictionaries/_pd_instr.md) [customCIF][0]{:.label-cif} + - [\_pd_instr.dtt2](dictionaries/_pd_instr.md) [customCIF][0]{:.label-cif} + - [\_pd_instr.2theta_bank](dictionaries/_pd_instr.md) + [customCIF][0]{:.label-cif} + - [\_pd_instr.alpha0](dictionaries/_pd_instr.md) [customCIF][0]{:.label-cif} + - [\_pd_instr.alpha1](dictionaries/_pd_instr.md) [customCIF][0]{:.label-cif} + - [\_pd_instr.beta0](dictionaries/_pd_instr.md) [customCIF][0]{:.label-cif} + - [\_pd_instr.beta1](dictionaries/_pd_instr.md) [customCIF][0]{:.label-cif} + - [\_pd_instr.sigma0](dictionaries/_pd_instr.md) [customCIF][0]{:.label-cif} + - [\_pd_instr.sigma1](dictionaries/_pd_instr.md) [customCIF][0]{:.label-cif} + - [\_pd_instr.sigma2](dictionaries/_pd_instr.md) [customCIF][0]{:.label-cif} +- [\_pd_meas](dictionaries/_pd_meas.md) [pdCIF][2]{:.label-cif} + - [\_pd_meas.time_of_flight](dictionaries/_pd_meas.md) [pdCIF][2]{:.label-cif} + - [\_pd_meas.intensity_total](dictionaries/_pd_meas.md) + [pdCIF][2]{:.label-cif} + - [\_pd_meas.intensity_total_su](dictionaries/_pd_meas.md) + [pdCIF][2]{:.label-cif} + +[sc-neut-cwl][3]{:.label-experiment} + +- [\_extinction](dictionaries/_extinction.md) [customCIF][0]{:.label-cif} + + - [\_extinction.model](dictionaries/_extinction.md) + [customCIF][0]{:.label-cif} + - [\_extinction.mosaicity](dictionaries/_extinction.md) + [customCIF][0]{:.label-cif} + - [\_extinction.radius](dictionaries/_extinction.md) + [customCIF][0]{:.label-cif} + +- [\_exptl_crystal](dictionaries/_exptl_crystal.md) [customCIF][0]{:.label-cif} + - [\_exptl_crystal.id](dictionaries/_exptl_crystal.md) + [customCIF][0]{:.label-cif} + - [\_exptl_crystal.scale](dictionaries/_exptl_crystal.md) + [customCIF][0]{:.label-cif} + + +[0]: # +[1]: https://www.iucr.org/resources/cif/dictionaries/browse/cif_core +[2]: https://www.iucr.org/resources/cif/dictionaries/browse/cif_pd +[3]: glossary.md + diff --git a/docs/dictionaries/_atom_site.md b/docs/dictionaries/_atom_site.md new file mode 100644 index 0000000..1a81a75 --- /dev/null +++ b/docs/dictionaries/_atom_site.md @@ -0,0 +1,62 @@ +[coreCIF][1]{:.label-cif} + +# \_atom_site + +Data items in this category record details about the atom sites in a crystal +structure, such as the positional coordinates and atomic displacement +parameters. Please see the +[IUCr page](https://www.iucr.org/__data/iucr/cifdic_html/3/CORE_DIC/CATOM_SITE.html) +for further details. + +## [\_atom_site.label](https://www.iucr.org/__data/iucr/cifdic_html/3/CORE_DIC/Iatom_site.label.html) + +This is a unique identifier for a particular site in the asymmetric unit of the +crystal unit cell. + +## [\_atom_site.type_symbol](https://www.iucr.org/__data/iucr/cifdic_html/3/CORE_DIC/Iatom_site.type_symbol.html) + +A code to identify the atom specie(s) occupying this site. + +## \_atom_site.fract + +Atom-site coordinates as fractions of the [\_cell_length](_cell.md) values. + +- [\_atom_site.fract_x](https://www.iucr.org/__data/iucr/cifdic_html/3/CORE_DIC/Iatom_site.fract_x.html) +- [\_atom_site.fract_y](https://www.iucr.org/__data/iucr/cifdic_html/3/CORE_DIC/Iatom_site.fract_y.html) +- [\_atom_site.fract_z](https://www.iucr.org/__data/iucr/cifdic_html/3/CORE_DIC/Iatom_site.fract_z.html) + +## [\_atom_site.occupancy](https://www.iucr.org/__data/iucr/cifdic_html/3/CORE_DIC/Iatom_site.occupancy.html) + +The fraction of the atom type present at this site. + +## [\_atom_site.ADP_type](https://www.iucr.org/__data/iucr/cifdic_html/3/CORE_DIC/Iatom_site.adp_type.html) + +Code for type of atomic displacement parameters used for the site. Currently +only `Biso` (isotropic B) is supported. + +## [\_atom_site.B_iso_or_equiv](https://www.iucr.org/__data/iucr/cifdic_html/3/CORE_DIC/Iatom_site.B_iso_or_equiv.html) + +Isotropic atomic displacement parameter, or equivalent isotropic atomic +displacement parameter, in angstroms squared. + +## [\_atom_site.site_symmetry_multiplicity](https://www.iucr.org/__data/iucr/cifdic_html/3/CORE_DIC/Iatom_site.site_symmetry_multiplicity.html) + +`optional parameter` + +The number of different sites that are generated by the application of the +space-group symmetry to the coordinates given for this site. It is equal to the +multiplicity given for this Wyckoff site in International Tables for +Crystallography Vol. A (2002). + +## [\_atom_site.Wyckoff_symbol](https://www.iucr.org/__data/iucr/cifdic_html/3/CORE_DIC/Iatom_site.Wyckoff_symbol.html) + +`optional parameter` + +The Wyckoff symbol (letter) as listed in the space-group tables of International +Tables for Crystallography Vol. A. + + +[0]: # +[1]: https://www.iucr.org/resources/cif/dictionaries/browse/cif_core +[2]: https://www.iucr.org/resources/cif/dictionaries/browse/cif_pd + diff --git a/docs/dictionaries/_cell.md b/docs/dictionaries/_cell.md new file mode 100644 index 0000000..5aeb12a --- /dev/null +++ b/docs/dictionaries/_cell.md @@ -0,0 +1,30 @@ +[coreCIF][1]{:.label-cif} + +# \_cell + +Data items in this category record details about the crystallographic cell +parameters and their measurement. Please see the +[IUCr page](https://www.iucr.org/__data/iucr/cifdic_html/3/CORE_DIC/CCELL.html) +for further details. + +## \_cell.angle + +The angles between the bounding cell axes in degrees. + +- [\_cell.angle_alpha](https://www.iucr.org/__data/iucr/cifdic_html/3/CORE_DIC/Icell.angle_alpha.html) +- [\_cell.angle_beta](https://www.iucr.org/__data/iucr/cifdic_html/3/CORE_DIC/Icell.angle_beta.html) +- [\_cell.angle_gamma](https://www.iucr.org/__data/iucr/cifdic_html/3/CORE_DIC/Icell.angle_gamma.html) + +## \_cell.length + +The lengths of each cell axis in angstroms. + +- [\_cell.length_a](https://www.iucr.org/__data/iucr/cifdic_html/3/CORE_DIC/Icell.length_a.html) +- [\_cell.length_b](https://www.iucr.org/__data/iucr/cifdic_html/3/CORE_DIC/Icell.length_b.html) +- [\_cell.length_c](https://www.iucr.org/__data/iucr/cifdic_html/3/CORE_DIC/Icell.length_c.html) + + +[0]: # +[1]: https://www.iucr.org/resources/cif/dictionaries/browse/cif_core +[2]: https://www.iucr.org/resources/cif/dictionaries/browse/cif_pd + diff --git a/docs/dictionaries/_diffrn_radiation.md b/docs/dictionaries/_diffrn_radiation.md new file mode 100644 index 0000000..e3c0a7e --- /dev/null +++ b/docs/dictionaries/_diffrn_radiation.md @@ -0,0 +1,21 @@ +[coreCIF][1]{:.label-cif} + +# \_diffrn_radiation + +Data items in this category describe the radiation used in measuring the +diffraction intensities. Please see the +[IUCr page](https://www.iucr.org/resources/cif/dictionaries/browse/cif_pd) for +further details. + +## [\_diffrn_radiation.probe](https://www.iucr.org/resources/cif/dictionaries/browse/cif_pd) + +The nature of the radiation used (i.e. the name of the subatomic particle or the +region of the electromagnetic spectrum). + +Supported values: `neutron` and `x-ray` + + +[0]: # +[1]: https://www.iucr.org/resources/cif/dictionaries/browse/cif_core +[2]: https://www.iucr.org/resources/cif/dictionaries/browse/cif_pd + diff --git a/docs/dictionaries/_diffrn_radiation_wavelength.md b/docs/dictionaries/_diffrn_radiation_wavelength.md new file mode 100644 index 0000000..4d20578 --- /dev/null +++ b/docs/dictionaries/_diffrn_radiation_wavelength.md @@ -0,0 +1,18 @@ +[coreCIF][1]{:.label-cif} + +# \_diffrn_radiation_wavelength + +Data items in this category describe the wavelength of radiation used in +diffraction measurements. Please see the +[IUCr page](https://www.iucr.org/resources/cif/dictionaries/browse/cif_pd) for +further details. + +## [\_diffrn_radiation_wavelength.wavelength](https://www.iucr.org/resources/cif/dictionaries/browse/cif_pd) + +Wavelength of the radiation used to measure the unit cell. + + +[0]: # +[1]: https://www.iucr.org/resources/cif/dictionaries/browse/cif_core +[2]: https://www.iucr.org/resources/cif/dictionaries/browse/cif_pd + diff --git a/docs/dictionaries/_exptl_crystal.md b/docs/dictionaries/_exptl_crystal.md new file mode 100644 index 0000000..8d568b2 --- /dev/null +++ b/docs/dictionaries/_exptl_crystal.md @@ -0,0 +1,7 @@ +[customCIF][0]{:.label-cif} + + +[0]: # +[1]: https://www.iucr.org/resources/cif/dictionaries/browse/cif_core +[2]: https://www.iucr.org/resources/cif/dictionaries/browse/cif_pd + diff --git a/docs/dictionaries/_extinction.md b/docs/dictionaries/_extinction.md new file mode 100644 index 0000000..8d568b2 --- /dev/null +++ b/docs/dictionaries/_extinction.md @@ -0,0 +1,7 @@ +[customCIF][0]{:.label-cif} + + +[0]: # +[1]: https://www.iucr.org/resources/cif/dictionaries/browse/cif_core +[2]: https://www.iucr.org/resources/cif/dictionaries/browse/cif_pd + diff --git a/docs/dictionaries/_pd_background.md b/docs/dictionaries/_pd_background.md new file mode 100644 index 0000000..8998547 --- /dev/null +++ b/docs/dictionaries/_pd_background.md @@ -0,0 +1,30 @@ +[pdCIF][2]{:.label-cif} + +# \_pd_background + +This category defines various background functions that could be used when +calculating diffractograms. Please see the +[IUCr page](https://www.iucr.org/resources/cif/dictionaries/browse/cif_pd) for +further details. + +## [\_pd_background.line_segment_X](https://www.iucr.org/resources/cif/dictionaries/browse/cif_pd) + +List of X-coordinates used to create many straight-line segments representing +the background in a calculated diffractogram. + +Supported values: `2theta` and `time-of-flight` + +## [\_pd_background.line_segment_intensity](https://www.iucr.org/resources/cif/dictionaries/browse/cif_pd) + +List of intensities used to create many straight-line segments representing the +background in a calculated diffractogram. + +## [\_pd_background.X_coordinate](https://www.iucr.org/resources/cif/dictionaries/browse/cif_pd) + +The type of X-coordinate against which the pd_background values were calculated. + + +[0]: # +[1]: https://www.iucr.org/resources/cif/dictionaries/browse/cif_core +[2]: https://www.iucr.org/resources/cif/dictionaries/browse/cif_pd + diff --git a/docs/dictionaries/_pd_calib.md b/docs/dictionaries/_pd_calib.md new file mode 100644 index 0000000..2b96a4c --- /dev/null +++ b/docs/dictionaries/_pd_calib.md @@ -0,0 +1,17 @@ +[customCIF][0]{:.label-cif} + +# \_pd_calib + +This section defines the parameters used for the calibration of the instrument, +similar to this +[IUCr section](https://www.iucr.org/resources/cif/dictionaries/browse/cif_pd). + +## [\_pd_calib.2theta_offset](https://www.iucr.org/resources/cif/dictionaries/browse/cif_pd) + +An offset angle (in degrees) used to calibrate 2θ. + + +[0]: # +[1]: https://www.iucr.org/resources/cif/dictionaries/browse/cif_core +[2]: https://www.iucr.org/resources/cif/dictionaries/browse/cif_pd + diff --git a/docs/dictionaries/_pd_instr.md b/docs/dictionaries/_pd_instr.md new file mode 100644 index 0000000..3975161 --- /dev/null +++ b/docs/dictionaries/_pd_instr.md @@ -0,0 +1,85 @@ +[customCIF][0]{:.label-cif} + +# \_pd_instr + +This section contains information relevant to the instrument used for the +diffraction measurement, similar to this +[IUCr section](https://www.iucr.org/resources/cif/dictionaries/browse/cif_pd). + +## [\_pd_instr.resolution](#) + +In general, the profile of a Bragg reflection centred at the peak position can +be approximated by mathematical convolution of contributions from the +instrument, called the instrumental resolution function, and from the +microstructure of the sample. Because many contributions to powder diffraction +peaks have a nearly Gaussian or Lorentzian shape, the pseudo-Voigt function, is +widely used to describe peak profiles in powder diffraction. + +Half-width parameters (normally characterising the instrumental resolution +function) as implemented in [CrysPy](https://cryspy.fr): + +- \_pd_instr.resolution_u +- \_pd_instr.resolution_v +- \_pd_instr.resolution_w + +Lorentzian isotropic microstrain parameter as implemented in +[CrysPy](https://cryspy.fr): + +- \_pd_instr.resolution_x + +Lorentzian isotropic particle size parameteras implemented in +[CrysPy](https://cryspy.fr): + +- \_pd_instr.resolution_y + +## [\_pd_instr.reflex_asymmetry](#) + +Peak profile asymmetry parameters as implemented in [CrysPy](https://cryspy.fr). + +- \_pd_instr.reflex_asymmetry_p1 +- \_pd_instr.reflex_asymmetry_p2 +- \_pd_instr.reflex_asymmetry_p3 +- \_pd_instr.reflex_asymmetry_p4 + +## [\_pd_instr.2theta_bank](#) + +Time-of-flight parameters as implemented in [CrysPy](https://cryspy.fr). + +## [\_pd_instr.dtt](#) + +Time-of-flight parameters as implemented in [CrysPy](https://cryspy.fr). + +- \_pd_instr.dtt1 +- \_pd_instr.dtt2 + +## [\_pd_instr.zero](#) + +Time-of-flight parameters as implemented in [CrysPy](https://cryspy.fr). + +## [\_pd_instr.alpha](#) + +Time-of-flight parameters as implemented in [CrysPy](https://cryspy.fr). + +- \_pd_instr.alpha0 +- \_pd_instr.alpha1 + +## [\_pd_instr.beta](#) + +Time-of-flight parameters as implemented in [CrysPy](https://cryspy.fr). + +- \_pd_instr.beta0 +- \_pd_instr.beta1 + +## [\_pd_instr.sigma](#) + +Time-of-flight parameters as implemented in [CrysPy](https://cryspy.fr). + +- \_pd_instr.sigma0 +- \_pd_instr.sigma1 +- \_pd_instr.sigma2 + + +[0]: # +[1]: https://www.iucr.org/resources/cif/dictionaries/browse/cif_core +[2]: https://www.iucr.org/resources/cif/dictionaries/browse/cif_pd + diff --git a/docs/dictionaries/_pd_meas.md b/docs/dictionaries/_pd_meas.md new file mode 100644 index 0000000..b294a96 --- /dev/null +++ b/docs/dictionaries/_pd_meas.md @@ -0,0 +1,29 @@ +[pdCIF][2]{:.label-cif} + +# \_pd_meas + +This section contains the measured diffractogram, similar to this +[IUCr section](https://www.iucr.org/resources/cif/dictionaries/browse/cif_pd). + +## [\_pd_meas.2theta_scan](https://raw.githubusercontent.com/COMCIFS/Powder_Dictionary/master/cif_pow.dic) + +2θ diffraction angle (in degrees) for intensity points measured in a scanning +method. + +## [\_pd_meas.time-of-flight](https://raw.githubusercontent.com/COMCIFS/Powder_Dictionary/master/cif_pow.dic) + +Measured time (in microseconds) for time-of-flight neutron measurements. + +## [\_pd_meas.intensity_total](https://raw.githubusercontent.com/COMCIFS/Powder_Dictionary/master/cif_pow.dic) + +Intensity recorded at each measurement point as a function of angle. + +## [\_pd_meas.intensity_total_su](https://raw.githubusercontent.com/COMCIFS/Powder_Dictionary/master/cif_pow.dic) + +Standard uncertainty of \_pd_meas.2theta_scan. + + +[0]: # +[1]: https://www.iucr.org/resources/cif/dictionaries/browse/cif_core +[2]: https://www.iucr.org/resources/cif/dictionaries/browse/cif_pd + diff --git a/docs/dictionaries/_pd_phase.md b/docs/dictionaries/_pd_phase.md new file mode 100644 index 0000000..df3f6d2 --- /dev/null +++ b/docs/dictionaries/_pd_phase.md @@ -0,0 +1,22 @@ +[pdCIF][2]{:.label-cif} + +# \_pd_phase_block + +A table of phases relevant to the current data block. Each phase is identified +by its data block identifier. Please see the +[IUCr page](https://www.iucr.org/resources/cif/dictionaries/browse/cif_pd) for +further details. + +## [\_pd_phase_block.id](https://www.iucr.org/resources/cif/dictionaries/browse/cif_pd) + +A block ID code identifying a block containing phase information. + +## \_pd_phase_block.scale + +Phase scale. + + +[0]: # +[1]: https://www.iucr.org/resources/cif/dictionaries/browse/cif_core +[2]: https://www.iucr.org/resources/cif/dictionaries/browse/cif_pd + diff --git a/docs/dictionaries/_space_group.md b/docs/dictionaries/_space_group.md new file mode 100644 index 0000000..883be10 --- /dev/null +++ b/docs/dictionaries/_space_group.md @@ -0,0 +1,25 @@ +[coreCIF][1]{:.label-cif} + +# \_space_group + +Contains all the data items that refer to the space group as a whole. Please see +the +[IUCr page](https://www.iucr.org/__data/iucr/cifdic_html/3/CORE_DIC/CSPACE_GROUP.html) +for further details. + +## [\_space_group.name_H-M_alt](https://www.iucr.org/__data/iucr/cifdic_html/3/CORE_DIC/Ispace_group.name_H-M_alt.html) + +The international Hermann-Mauguin space-group symbol as defined in International +Tables for Crystallography Volume A. It allows any Hermann-Mauguin symbol to be +given. + +## [\_space_group.IT_coordinate_system_code](https://www.iucr.org/__data/iucr/cifdic_html/3/CORE_DIC/Ispace_group.IT_coordinate_system_code.html) + +A qualifier taken from the enumeration list identifying which setting in +International Tables for Crystallography Volume A (2002) (IT) is used. + + +[0]: # +[1]: https://www.iucr.org/resources/cif/dictionaries/browse/cif_core +[2]: https://www.iucr.org/resources/cif/dictionaries/browse/cif_pd + diff --git a/docs/easyscience.md b/docs/easyscience.md new file mode 100644 index 0000000..d15a61b --- /dev/null +++ b/docs/easyscience.md @@ -0,0 +1,102 @@ +# The EasyScience framework + +EasyScience is a framework of software tools that can be used to build +experimental data analysis packages. For example, it has already been used in +the development of [EasyDiffraction] and [EasyReflectometry]. Two more packages +are about to be started: EasyImaging (Bragg edge imaging) and EasyDynamics +(Quasielastic neutron scattering, QENS). + +The framework consists of both front- and back-end elements, known as [EasyApp] +and [EasyScience], respectively. The front-end provides a shared library of +graphical interface elements that can be used to build a graphical user +interface. The back-end offers a toolset to perform model-dependent analysis, +including the ability to plug-in existing calculation engines. + +Below is a diagram illustrating the relationship between the modules of the +EasyScience framework: + + + + + EasyDiffractionBkg + Diffraction + + + + EasyDiffraction + + + EasyDiffractionLib + + + + EasyDiffractionApp + + + + + TechniqueIndependantBkg + Generic + + + + EasyBackend + + + EasyCore + + + + EasyCrystallography + + + + + + + + + + EasyFrontend + + + EasyApp + + + + + + + + EasyReflectometryBkg + Reflectometry + + + + EasyReflectometry + + + EasyReflectometryLib + + + + EasyReflectometryApp + + + + + + + + + + + + + + +[EasyDiffraction]: https://easydiffraction.org +[EasyReflectometry]: https://easyreflectometry.org +[EasyApp]: https://github.com/easyscience/easyapp +[EasyScience]: https://github.com/easyscience/easyscience + diff --git a/docs/experiment.md b/docs/experiment.md new file mode 100644 index 0000000..bbedf8e --- /dev/null +++ b/docs/experiment.md @@ -0,0 +1,277 @@ +# Experiment + +This section describes different types of experimental data which +EasyDiffraction can handle. + +## CIF-based description + +The following examples show the CIF data blocks for different types of +diffraction experiments supported in EasyDiffraction. + +### [pd-neut-cwl][3]{:.label-experiment} + + +
+
+data_hrpt
+
+_diffrn_radiation.probe                 neutron
+_diffrn_radiation_wavelength.wavelength 1.494
+
+_pd_calib.2theta_offset 0.6225(4)
+
+_pd_instr.resolution_u  0.0834
+_pd_instr.resolution_v -0.1168
+_pd_instr.resolution_w  0.123
+_pd_instr.resolution_x  0
+_pd_instr.resolution_y  0.0797
+
+_pd_instr.reflex_asymmetry_p1 0
+_pd_instr.reflex_asymmetry_p2 0
+_pd_instr.reflex_asymmetry_p3 0
+_pd_instr.reflex_asymmetry_p4 0
+
+loop_
+_pd_phase_block.id
+_pd_phase_block.scale
+lbco 9.0976(3)
+
+loop_
+_pd_background.line_segment_X
+_pd_background.line_segment_intensity
+_pd_background.X_coordinate
+ 10  174.3  2theta
+ 20  159.8  2theta
+ 30  167.9  2theta
+ 50  166.1  2theta
+ 70  172.3  2theta
+ 90  171.1  2theta
+110  172.4  2theta
+130  182.5  2theta
+150  173.0  2theta
+165  171.1  2theta
+
+loop_
+_pd_meas.2theta_scan
+_pd_meas.intensity_total
+_pd_meas.intensity_total_su
+ 10.00  167  12.6
+ 10.05  157  12.5
+ 10.10  187  13.3
+ 10.15  197  14.0
+ 10.20  164  12.5
+ 10.25  171  13.0
+...
+164.60  153  20.7
+164.65  173  30.1
+164.70  187  27.9
+164.75  175  38.2
+164.80  168  30.9
+164.85  109  41.2
+
+
+ + +### [pd-neut-tof][3]{:.label-experiment} + + +
+
+data_wish
+
+_diffrn_radiation.probe neutron
+
+_pd_instr.2theta_bank 152.827
+
+_pd_instr.dtt1 20773.1(3)
+_pd_instr.dtt2    -1.08308
+_pd_instr.zero   -13.7(5)
+
+_pd_instr.alpha0 -0.009(1)
+_pd_instr.alpha1  0.109(2)
+_pd_instr.beta0   0.00670(3)
+_pd_instr.beta1   0.0100(3)
+_pd_instr.sigma0  0
+_pd_instr.sigma1  0
+_pd_instr.sigma2 15.7(8)
+
+loop_
+_pd_phase_block.id
+_pd_phase_block.scale
+ncaf 1.093(5)
+
+loop_
+_pd_background.line_segment_X
+_pd_background.line_segment_intensity
+_pd_background.X_coordinate
+  9162.3  465(38) time-of-flight
+ 11136.8  593(30) time-of-flight
+ 14906.5  546(18) time-of-flight
+ 17352.2  496(14) time-of-flight
+ 20179.5  452(10) time-of-flight
+ 22176.0  468(12) time-of-flight
+ 24644.7  380(6)  time-of-flight
+ 28257.2  378(4)  time-of-flight
+ 34034.4  328(4)  time-of-flight
+ 41214.6  323(3)  time-of-flight
+ 49830.9  273(3)  time-of-flight
+ 58204.9  260(4)  time-of-flight
+ 70186.9  262(5)  time-of-flight
+ 82103.2  268(5)  time-of-flight
+102712.0  262(15) time-of-flight
+
+loop_
+_pd_meas.time_of_flight
+_pd_meas.intensity_total
+_pd_meas.intensity_total_su
+  9001.0  616.523  124.564
+  9006.8  578.769  123.141
+  9012.6  574.184  120.507
+  9018.5  507.739  111.300
+  9024.3  404.672  101.616
+  9030.1  469.244  107.991
+...
+103085.0  275.072   60.978
+103151.4  214.187   55.675
+103217.9  256.211   62.825
+103284.4  323.872   73.082
+103351.0  242.382   65.736
+103417.6  277.666   73.837
+
+
+ + +### [sc-neut-cwl][3]{:.label-experiment} + + +
+
+data_heidi
+
+_diffrn_radiation.probe                 neutron
+_diffrn_radiation_wavelength.wavelength 0.793
+
+_pd_calib.2theta_offset 0.6225(4)
+
+_pd_instr.resolution_u  0.0834
+_pd_instr.resolution_v -0.1168
+_pd_instr.resolution_w  0.123
+_pd_instr.resolution_x  0
+_pd_instr.resolution_y  0.0797
+
+_pd_instr.reflex_asymmetry_p1 0
+_pd_instr.reflex_asymmetry_p2 0
+_pd_instr.reflex_asymmetry_p3 0
+_pd_instr.reflex_asymmetry_p4 0
+
+loop_
+_exptl_crystal.id
+_exptl_crystal.scale
+tbti 2.92(6)
+
+loop_
+_refln.index_h
+_refln.index_k
+_refln.index_l
+_refln.intensity_meas
+_refln.intensity_meas_su
+ 1  1  1   194.5677    2.3253
+ 2  2  0    22.6319    1.1233
+ 3  1  1    99.2917    2.5620
+ 2  2  2   219.2877    3.2522
+...
+16  8  8    29.3063   12.6552
+17  7  7  1601.5154  628.8915
+13 13  7  1176.0896  414.6018
+19  5  1     0.8334   20.4207
+15  9  9    10.9864    8.0650
+12 12 10    14.4074   11.3800
+
+
+ + +## Other supported data files + +If you do not have a CIF file with both the instrumental parameters and measured data, as in the example (hrpt.cif) from the previous section, you can import only measured data. In that case, the data are then automatically converted into CIF with default parameters. These can be later edited in the code. + +The following measured data formats are supported: + +* If standard deviations of measured intensities are present, the file should have either `*.xye` or `*.xys` extension and contain the following 3 columns: + * [\_pd_meas.2theta\_scan](dictionaries/_pd_meas.md), + * [\_pd_meas.intensity\_total](dictionaries/_pd_meas.md), + * [\_pd_meas.intensity\_total\_su](dictionaries/_pd_meas.md). +* If standard deviations of measured intensities are not given, the file should have `*.xy` extension and contain the following 2 columns: + * [\_pd_meas.2theta\_scan](dictionaries/_pd_meas.md), + * [\_pd_meas.intensity\_total](dictionaries/_pd_meas.md). + +In the second case, the standard deviations [\_pd_meas.intensity\_total\_su](dictionaries/_pd_meas.md) are calculated as the square root of the measured intensities [\_pd_meas.intensity\_total](dictionaries/_pd_meas.md). + +Optional comments with `#` are possible in data file headers. + +Here are some examples: + +### example1.xye + + +
+
+# 2theta  intensity    su
+   10.00     167      12.6
+   10.05     157      12.5
+   10.10     187      13.3
+   10.15     197      14.0
+   10.20     164      12.5
+  ...
+  164.65     173      30.1
+  164.70     187      27.9
+  164.75     175      38.2
+  164.80     168      30.9
+  164.85     109      41.2
+
+
+ + +### example2.xy + + +
+
+# 2theta  intensity
+   10.00     167    
+   10.05     157    
+   10.10     187    
+   10.15     197    
+   10.20     164    
+  ...
+  164.65     173    
+  164.70     187    
+  164.75     175    
+  164.80     168    
+  164.85     109  
+
+
+ + +### example3.xy + + +
+
+10  167.3    
+10.05  157.4    
+10.1  187.1    
+10.15  197.8    
+10.2  164.9    
+...
+164.65  173.3    
+164.7  187.5    
+164.75  175.8    
+164.8  168.1    
+164.85  109     
+
+
+ + + +[3]: glossary.md + diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..f9049bf --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,162 @@ +# Getting started + +## Requirements + +The EasyDiffraction library is developed in Python, so Python must be installed +on your system. The library is compatible with Python versions 3.9 through 3.12. + +## Environment setup optional { #environment-setup data-toc-label="Environment setup" } + +We recommend using a virtual environment – an isolated Python runtime where any +packages you install or update are contained within that environment. If you +encounter issues, you can simply delete and recreate the environment. Setting it +up is straightforward: + +- Create a new virtual environment with: + ```console + python3 -m venv venv + ``` + + + +- Activate the environment with: + + === ":material-apple: macOS" + ```console + . venv/bin/activate + ``` + === ":fontawesome-brands-windows: Windows" + ```console + . venv/Scripts/activate + ``` + === ":material-linux: Linux" + ```console + . venv/bin/activate + ``` + + + +Your terminal should now print `(venv)` before the prompt, which is how you know +that you are inside the virtual environment that you just created. + +- Exit the environment with: + ``` + deactivate + ``` + +## Installation + +### From PyPI recommended { #from-pypi data-toc-label="From PyPI" } + +EasyDiffraction is published on the Python Package Index (PyPI) repository and +can be installed with the package installer for Python (pip), ideally by using a +[virtual environment](#environment-setup). + +We recommend installing the latest release of EasyDiffraction with the `charts` +extras, which include optional dependencies used for simplified visualization of +charts and tables. This can be especially useful for running the Jupyter +Notebook examples. To do so, use the following command: + +```console +pip install 'easydiffraction[charts]' +``` + +If only the core functionality is needed, the library can be installed simply +with: + +```console +pip install easydiffraction +``` + +To install a specific version of EasyDiffraction, e.g. 0.1.3, use: + +```console +pip install 'easydiffraction==0.1.3' +``` + +Upgrading to the latest version can be done with: + +```console +pip install --upgrade --force-reinstall easydiffraction +``` + +To show the currently installed version, use: + +```console +pip show easydiffraction +``` + +### From GitHub + +Installing an unreleased version is not recommended and should only be done for +testing purposes. + +Here is an example of how to install EasyDiffraction directly from our GitHub +repository, e.g., from the `develop` branch: + +```console +pip install git+https://github.com/EasyScience/EasyDiffractionLib@develop +``` + +To do the same with extra dependencies, use: + +```console +pip install 'easydiffraction[charts] @ git+https://github.com/EasyScience/EasyDiffractionLib@develop' +``` + +## Examples + +We have a collection of Jupyter Notebook examples that demonstrate how to use +EasyDiffraction for various tasks. These examples are presented in the +[How to use](how-to-use/index.md#how-to-use) section of the documentation as +static HTML pages. + +You can also run these Jupyter Notebook examples yourself either locally or in +Google Colab. + +These Jupyter Notebook examples can be downloaded either one by one from the +[How to use](how-to-use/index.md#how-to-use) section or all together as a zip +archive from the +[EasyDiffraction releases](https://github.com/EasyScience/EasyDiffractionLib/releases/latest). + +### Run locally + +To run the examples locally, you need to install Jupyter Notebook or JupyterLab. +Here are the steps to take in the case of Jupyter Notebook: + +- Install Jupyter Notebook: + ```console + pip install notebook + ``` +- Download EasyDiffraction examples from GitHub for the latest release, e.g., + using curl: + ```console + curl --location --remote-name https://github.com/EasyScience/EasyDiffractionLib/releases/latest/download/examples.zip + ``` +- Unzip the downloaded archive: + ```console + unzip examples.zip + ``` +- Run Jupyter Notebook server in the `examples/` directory: + ```console + jupyter notebook examples/ + ``` +- Open your web browser and go to: + ```console + http://localhost:8888/ + ``` +- Select one of the `*.ipynb` files. + +### Via Google Colab + +!!! note + + To run the examples in Google Colab, you need to have a Google account. + +Google Colab is a free cloud service that allows you to run Jupyter Notebooks +online, enabling you to run the examples without installing anything on your +local machine. + +In the top right corner of each example, under the +[How to use](how-to-use/index.md#how-to-use) section, you will find a button to +open that example in Google Colab :google-colab: diff --git a/docs/glossary.md b/docs/glossary.md new file mode 100644 index 0000000..b324fc8 --- /dev/null +++ b/docs/glossary.md @@ -0,0 +1,34 @@ +# Glossary + +This page contains the most common abbreviations used in EasyDiffraction +documentation. + +## Dictionary type labels + +- [coreCIF][1]{:.label-cif} Core CIF dictionary by the + [IUCr](https://www.iucr.org). +- [pdCIF][2]{:.label-cif} Powder CIF dictionary by the + [IUCr](https://www.iucr.org). +- [customCIF][0]{:.label-cif} Custom CIF dictionary by the EasyDiffraction + developers. + +## Experiment type labels + +### Neutron diffraction + +- [pd-neut-cwl][0]{:.label-experiment} Powder neutron diffraction with constant + wavelength. +- [pd-neut-tof][0]{:.label-experiment} Powder neutron diffraction with + time-of-flight. +- [sc-neut-cwl][0]{:.label-experiment} Single crystal neutron diffraction with + constant wavelength. + +### X-ray diffraction + +- [pd-xray][0]{:.label-experiment} Powder X-ray diffraction. + + +[0]: # +[1]: https://www.iucr.org/resources/cif/dictionaries/browse/cif_core +[2]: https://www.iucr.org/resources/cif/dictionaries/browse/cif_pd + diff --git a/docs/how-to-use/index.md b/docs/how-to-use/index.md new file mode 100644 index 0000000..8d691fa --- /dev/null +++ b/docs/how-to-use/index.md @@ -0,0 +1,10 @@ +# How to use + +This section provides a collection of Jupyter Notebook examples that demonstrate +how to use EasyDiffraction for various tasks. These examples are presented as +static HTML pages. + +In the top right corner of each example, you will find + +- a button to download the example as a Jupyter Notebook :material-download: +- a button to open that example in Google Colab :google-colab: diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..7d0788a --- /dev/null +++ b/docs/index.md @@ -0,0 +1,30 @@ +![](assets/images/ed-logo_dark.svg#gh-dark-mode-only)![](assets/images/ed-logo_light.svg#gh-light-mode-only) + +# Making diffraction data analysis easy + +## About + +EasyDiffraction is scientific software for calculating neutron powder +diffraction patterns based on a structural model and refining its parameters +against experimental data. + +EasyDiffraction is distributed as both a cross-platform desktop application and +a Python library. + +Here you can find instructions for using the EasyDiffraction Python library. +Documentation for the EasyDiffraction graphical user interface can be found +[elsewhere](https://docs.easydiffraction.org/app). + +EasyDiffraction is part of the +[EasyScience framework](https://easyscience.software), briefly described in the +next section. + +## License + +EasyDiffraction is licensed under the +[BSD 3-Clause License](https://raw.githubusercontent.com/EasyScience/EasyDiffractionLib/master/LICENSE). + +## Latest release + +The latest release of EasyDiffraction Python library is +[{{ vars.release_version }}](https://github.com/EasyScience/EasyDiffractionLib/releases/latest). diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml new file mode 100644 index 0000000..f97ca6f --- /dev/null +++ b/docs/mkdocs.yml @@ -0,0 +1,39 @@ +# Project information +site_name: EasyDiffraction Library +site_url: https://easyscience.github.io/diffraction-lib + +# Repository +repo_url: https://github.com/easyscience/diffraction-lib +edit_uri: edit/develop/docs/ + +# Copyright +copyright: © 2025 EasyDiffraction + +# Format and layout of the global navigation for the site +not_in_nav: | + dictionaries +nav: + - Introduction: index.md + - EasyScience: easyscience.md + - Getting started: getting-started.md + - Glossary: glossary.md + - Dictionaries: dictionaries.md + - Project structure: project-structure.md + - Model: model.md + - Experiment: experiment.md + - Analysis: analysis.md + - How to use: + - how-to-use/index.md + - Basic: + - Define model: examples/Define-model.ipynb + - Define experiment: examples/Define-experiment.ipynb + - Simulation: + - pd-xray NaCl: examples/Simulation_pd-xray_NaCl.ipynb + - Fitting: + - pd-neut-cwl LBCO-HRPT: examples/Fitting_pd-neut-cwl_LBCO-HRPT.ipynb + - pd-neut-tof Si-SEPD: examples/Fitting_pd-neut-tof_Si-SEPD.ipynb + - pd-neut-tof NCAF-WISH: examples/Fitting_pd-neut-tof_NCAF-WISH.ipynb + - Advanced fitting: + - MCMC pd-neut-tof NCAF-WISH: examples/Fitting-emcee_pd-neut-cwl_LBCO-HRPT.ipynb + - Extra: + - Change minimizer: examples/Change-minimizer.ipynb diff --git a/docs/model.md b/docs/model.md new file mode 100644 index 0000000..06f035a --- /dev/null +++ b/docs/model.md @@ -0,0 +1,9 @@ +# Model + +EasyDiffraction allow you to load the crystallographic model in CIF format. The +model is then used to calculate the diffraction pattern, which is compared to +the experimental data. The model parameters can be refined to improve the +agreement between the calculated and measured data. + +An example of the CIF-based model has been given in the +[Project structure](project-structure.md) section. diff --git a/docs/project-structure.md b/docs/project-structure.md new file mode 100644 index 0000000..f1d3bf3 --- /dev/null +++ b/docs/project-structure.md @@ -0,0 +1,151 @@ +# Project structure + +## CIF-based project files + +Example project structure for the constant wavelength powder neutron diffraction +measurement is given below: + + + +
+
+La0.5Ba0.5CoO3     - Project directory.
+├── project.cif    - Main project description file.
+├── models         - Folder with individual crystallographic phases.
+│   ├── lbco.cif   - File with La0.5Ba0.5CoO3 phase parameters.
+│   └── ...
+├── experiments    - Folder with instrumental parameters and measured data.
+│   ├── hrpt.cif   - Measured data from HRPT@PSI & instrumental parameters.
+│   └── ...
+└── summary
+    └── report.cif - Summary report after structure refinement.
+
+
+ + + +Here is the content of the project files: + +### project.cif + + + +
+
+data_La0.5Ba0.5CoO3
+
+_project.description "neutrons, powder, constant wavelength, HRPT@PSI"
+
+loop_
+_model.cif_file_name
+lbco.cif
+
+loop_
+_experiment.cif_file_name
+hrpt.cif
+
+
+ + + +### models / lbco.cif + + + +
+
+data_lbco
+
+_space_group.name_H-M_alt              "P m -3 m"
+_space_group.IT_coordinate_system_code 1
+
+_cell.length_a      3.8909(1)
+_cell.length_b      3.8909
+_cell.length_c      3.8909
+_cell.angle_alpha  90
+_cell.angle_beta   90
+_cell.angle_gamma  90
+
+loop_
+_atom_site.label
+_atom_site.type_symbol
+_atom_site.fract_x
+_atom_site.fract_y
+_atom_site.fract_z
+_atom_site.occupancy
+_atom_site.adp_type
+_atom_site.B_iso_or_equiv
+La La   0   0   0     0.5  Biso 0.4958
+Ba Ba   0   0   0     0.5  Biso 0.4943
+Co Co   0.5 0.5 0.5   1    Biso 0.2567
+O  O    0   0.5 0.5   1    Biso 1.4041
+
+
+ + + +### experiments / hrpt.cif + + + +
+
+data_hrpt
+
+_diffrn_radiation.probe                 neutron
+_diffrn_radiation_wavelength.wavelength 1.494
+
+_pd_calib.2theta_offset 0.6225(4)
+
+_pd_instr.resolution_u  0.0834
+_pd_instr.resolution_v -0.1168
+_pd_instr.resolution_w  0.123
+_pd_instr.resolution_x  0
+_pd_instr.resolution_y  0.0797
+
+_pd_instr.reflex_asymmetry_p1 0
+_pd_instr.reflex_asymmetry_p2 0
+_pd_instr.reflex_asymmetry_p3 0
+_pd_instr.reflex_asymmetry_p4 0
+
+loop_
+_pd_phase_block.id
+_pd_phase_block.scale
+lbco 9.0976(3)
+
+loop_
+_pd_background.line_segment_X
+_pd_background.line_segment_intensity
+_pd_background.X_coordinate
+ 10  174.3  2theta
+ 20  159.8  2theta
+ 30  167.9  2theta
+ 50  166.1  2theta
+ 70  172.3  2theta
+ 90  171.1  2theta
+110  172.4  2theta
+130  182.5  2theta
+150  173.0  2theta
+165  171.1  2theta
+
+loop_
+_pd_meas.2theta_scan
+_pd_meas.intensity_total
+_pd_meas.intensity_total_su
+ 10.00  167  12.6
+ 10.05  157  12.5
+ 10.10  187  13.3
+ 10.15  197  14.0
+ 10.20  164  12.5
+ 10.25  171  13.0
+...
+164.60  153  20.7
+164.65  173  30.1
+164.70  187  27.9
+164.75  175  38.2
+164.80  168  30.9
+164.85  109  41.2
+
+
+ + diff --git a/pyproject.toml b/pyproject.toml index 8e9139d..48b36b3 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -33,21 +33,31 @@ dependencies = [ [project.optional-dependencies] dev = [ - 'build', # Building the package - 'jinja2', # Templating for the documentation - 'nbmake', # Building notebooks - 'nbqa', # Linting and formatting notebooks - 'pytest', # Testing - 'pytest-cov', # Coverage - 'pytest-xdist', # Enable parallel testing - 'ruff', # Linting and formatting code - 'versioningit', # Versioning + 'build', # Building the package + 'jinja2', # Templating for the documentation + 'nbmake', # Building notebooks + 'nbqa', # Linting and formatting notebooks + 'pytest', # Testing + 'pytest-cov', # Coverage + 'pytest-xdist', # Enable parallel testing + 'ruff', # Linting and formatting code + 'validate-pyproject[all]', # Validate pyproject.toml + 'versioningit', # Versioning ] charts = [ - 'darkdetect', # Detecting dark mode - 'pandas', # Displaying tables in juptyer notebooks - 'plotly', # Interactive plots - 'py3Dmol', # Visualisation of crystal structures + 'darkdetect', # Detecting dark mode + 'pandas', # Displaying tables in juptyer notebooks + 'plotly<6.0.0', # Interactive plots. 0.6.0 => Empty charts in Jupyter notebooks ... + 'py3Dmol', # Visualisation of crystal structures +] +docs = [ + 'mkdocs', # Static site generator + 'mkdocs-material', # Documentation framework on top of MkDocs + 'mkdocs-autorefs<1.3.0', # MkDocs: Auto-references support. 1.3.0 => DeprecationWarning: Setting a fallback anchor function is deprecated and ... + 'mkdocs-jupyter', # MkDocs: Jupyter notebook support + 'mkdocs-plugin-inline-svg', # MkDocs: Inline SVG support + 'mkdocs-markdownextradata-plugin', # MkDocs: Markdown extra data support, such as global variables + 'mkdocstrings', # MkDocs: Python docstring support ] pdf = [ 'diffpy.pdffit2', # Calculations of atomic pair distribution function diff --git a/tools/build_docs.sh b/tools/build_docs.sh new file mode 100755 index 0000000..016182c --- /dev/null +++ b/tools/build_docs.sh @@ -0,0 +1,3 @@ +echo "\033[0;33m:::::: Build docs (http://127.0.0.1:8000)\033[0m" +export JUPYTER_PLATFORM_DIRS=1 +mkdocs serve diff --git a/tools/cleanup_docs.sh b/tools/cleanup_docs.sh new file mode 100755 index 0000000..b220a0f --- /dev/null +++ b/tools/cleanup_docs.sh @@ -0,0 +1,10 @@ +echo "\033[0;33m:::::: Clean up after building documentation\033[0m" +rm -rf site/ +rm -rf docs/assets/ +rm -rf includes/ +rm -rf overrides/ +rm -rf docs/examples/ +rm -rf node_modules/ +rm mkdocs.yml +rm package-lock.json +rm package.json diff --git a/tools/linting_and_formatting.sh b/tools/code_quality.sh similarity index 77% rename from tools/linting_and_formatting.sh rename to tools/code_quality.sh index bcdc114..718dd07 100755 --- a/tools/linting_and_formatting.sh +++ b/tools/code_quality.sh @@ -1,3 +1,6 @@ +echo "\033[0;33m:::::: Check the validity of pyproject.toml\033[0m" +validate-pyproject pyproject.toml + echo "\033[0;33m:::::: Check and fix code linting\033[0m" ruff check . --fix diff --git a/tools/install_deps.sh b/tools/install_deps.sh new file mode 100755 index 0000000..948da6d --- /dev/null +++ b/tools/install_deps.sh @@ -0,0 +1,5 @@ +echo "\033[0;33m:::::: Install Python dependencies\033[0m" +pip install '.[dev,charts,docs]' + +echo "\033[0;33m:::::: Install npm dependencies\033[0m" +npm install prettier prettier-plugin-toml --save-dev --save-exact diff --git a/tools/prepare_docs.sh b/tools/prepare_docs.sh new file mode 100755 index 0000000..da3ebbb --- /dev/null +++ b/tools/prepare_docs.sh @@ -0,0 +1,21 @@ +echo "\033[0;33m:::::: Add the extra files from the ../assets-docs\033[0m" +cp -R ../assets-docs/docs/assets/ docs/assets/ +cp -R ../assets-docs/includes/ includes/ +cp -R ../assets-docs/overrides/ overrides/ + +echo "\033[0;33m:::::: Add the extra files from the ../assets-branding\033[0m" +mkdir -p docs/assets/images/ +cp ../assets-branding/EasyDiffraction/logos/ed-logo_dark.svg docs/assets/images/ +cp ../assets-branding/EasyDiffraction/logos/ed-logo_light.svg docs/assets/images/ +cp ../assets-branding/EasyDiffraction/logos/edl-logo_dark.svg docs/assets/images/logo_dark.svg +cp ../assets-branding/EasyDiffraction/logos/edl-logo_light.svg docs/assets/images/logo_light.svg +cp ../assets-branding/EasyDiffraction/icons/ed-icon_256x256.png docs/assets/images/favicon.png +mkdir -p overrides/.icons/ +cp ../assets-branding/EasyDiffraction/icons/ed-icon_bw.svg overrides/.icons/easydiffraction.svg +cp ../assets-branding/EasyScienceOrg/icons/eso-icon_bw.svg overrides/.icons/easyscience.svg + +echo "\033[0;33m:::::: Add Jupyter notebooks from the project to the docs/\033[0m" +cp -R examples/ docs/examples/ + +echo "\033[0;33m:::::: Create the mkdocs.yml configuration file\033[0m" +cat ../assets-docs/mkdocs.yml docs/mkdocs.yml > mkdocs.yml