{"id":32175937,"url":"https://github.com/fable-3dxrd/xrd_simulator","last_synced_at":"2025-10-21T19:52:04.651Z","repository":{"id":51563968,"uuid":"389285191","full_name":"FABLE-3DXRD/xrd_simulator","owner":"FABLE-3DXRD","description":"Tools for simulating x-ray diffraction. Detailed documentation is found at the below link.","archived":false,"fork":false,"pushed_at":"2025-05-14T18:58:23.000Z","size":32808,"stargazers_count":35,"open_issues_count":2,"forks_count":14,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-21T19:51:42.335Z","etag":null,"topics":["diffraction","diffraction-analysis","diffraction-pattern","polycrystal","xray-crystallography","xray-diffraction","xray-diffraction-analysis","xray-images","xrd"],"latest_commit_sha":null,"homepage":"https://fable-3dxrd.github.io/xrd_simulator/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FABLE-3DXRD.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-07-25T07:10:26.000Z","updated_at":"2025-10-01T02:09:30.000Z","dependencies_parsed_at":"2023-01-23T12:46:09.749Z","dependency_job_id":"0ef88c7a-e855-44b5-b7f8-0e0140ea59e2","html_url":"https://github.com/FABLE-3DXRD/xrd_simulator","commit_stats":{"total_commits":355,"total_committers":3,"mean_commits":"118.33333333333333","dds":"0.46197183098591554","last_synced_commit":"5a7df080e9f26b416157b75a9a006cd48c60be52"},"previous_names":["axelhenningsson/xrd_simulator"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/FABLE-3DXRD/xrd_simulator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FABLE-3DXRD%2Fxrd_simulator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FABLE-3DXRD%2Fxrd_simulator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FABLE-3DXRD%2Fxrd_simulator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FABLE-3DXRD%2Fxrd_simulator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FABLE-3DXRD","download_url":"https://codeload.github.com/FABLE-3DXRD/xrd_simulator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FABLE-3DXRD%2Fxrd_simulator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280325298,"owners_count":26311419,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-21T02:00:06.614Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["diffraction","diffraction-analysis","diffraction-pattern","polycrystal","xray-crystallography","xray-diffraction","xray-diffraction-analysis","xray-images","xrd"],"created_at":"2025-10-21T19:52:02.888Z","updated_at":"2025-10-21T19:52:04.646Z","avatar_url":"https://github.com/FABLE-3DXRD.png","language":"Python","readme":".. image:: https://github.com/FABLE-3DXRD/xrd_simulator/blob/main/docs/source/images/logo.png?raw=true\n\n.. image:: https://img.shields.io/pypi/pyversions/xrd-simulator.svg?\n\t:target: https://pypi.org/project/xrd-simulator/\n\n.. image:: https://github.com/FABLE-3DXRD/xrd_simulator/actions/workflows/python-package-run-tests-linux-py38.yml/badge.svg?\n\t:target: https://github.com/FABLE-3DXRD/xrd_simulator/actions/workflows/python-package-run-tests-linux-py38.yml\n\n.. image:: https://github.com/FABLE-3DXRD/xrd_simulator/actions/workflows/pages/pages-build-deployment/badge.svg?\n\t:target: https://github.com/FABLE-3DXRD/xrd_simulator/actions/workflows/pages/pages-build-deployment/\n\n.. image:: https://badge.fury.io/py/xrd-simulator.svg?\n\t:target: https://pypi.org/project/xrd-simulator/\n\n.. image:: https://anaconda.org/conda-forge/vsc-install/badges/platforms.svg?\n\t:target: https://anaconda.org/conda-forge/xrd_simulator/\n\n.. image:: https://anaconda.org/conda-forge/xrd_simulator/badges/latest_release_relative_date.svg?\n\t:target: https://anaconda.org/conda-forge/xrd_simulator/\n\n===================================================================================================\nSimulate X-ray Diffraction from Polycrystals in 3D.\n===================================================================================================\n.. image:: https://img.shields.io/badge/stability-alpha-f4d03f.svg?\n\t:target: https://github.com/FABLE-3DXRD/xrd_simulator/\n\n\nThe **X**-**R** ay **D** iffraction **SIMULATOR** package defines polycrystals as a mesh of tetrahedral single crystals\nand simulates diffraction as collected by a 2D discretized detector array while the sample is rocked\naround an arbitrary rotation axis. The full journal paper associated to the release of this code can be found here:\n\n*xrd_simulator: 3D X-ray diffraction simulation software supporting 3D polycrystalline microstructure morphology descriptions\nHenningsson, A. \u0026 Hall, S. A. (2023). J. Appl. Cryst. 56, 282-292.*\n`https://doi.org/10.1107/S1600576722011001`_\n\n``xrd_simulator`` was originally developed with the hope to answer questions about measurement optimization in\nscanning x-ray diffraction experiments. However, ``xrd_simulator`` can simulate a wide range of experimental\ndiffraction setups. The essential idea is that the sample and beam topology can be arbitrarily specified,\nand their interaction simulated as the sample is rocked. This means that standard \"non-powder\" experiments\nsuch as `scanning-3dxrd`_ and full-field `3dxrd`_ (or HEDM if you like) can be simulated as well as more advanced\nmeasurement sequences such as helical scans for instance. It is also possible to simulate `powder like`_\nscenarios using orientation density functions as input.\n\n===================================================================================================\nIntroduction\n===================================================================================================\nBefore reading all the boring documentation (`which is hosted here`_) let's dive into some end to end\nexamples to get us started on a good flavour.\n\nThe ``xrd_simulator`` is built around four python objects which reflect a diffraction experiment:\n\n   * A **beam** of x-rays (using the ``xrd_simulator.beam`` module)\n   * A 2D area **detector** (using the ``xrd_simulator.detector`` module)\n   * A 3D **polycrystal** sample (using the ``xrd_simulator.polycrystal`` module)\n   * A rigid body sample **motion** (using the ``xrd_simulator.motion`` module)\n\nOnce these objects are defined it is possible to let the **detector** collect scattering of the **polycrystal**\nas the sample undergoes the prescribed rigid body **motion** while being illuminated by the xray **beam**.\n\nLet's go ahead and build ourselves some x-rays:\n\n   .. code:: python\n\n      import numpy as np\n      from xrd_simulator.beam import Beam\n      # The beam of xrays is represented as a convex polyhedron\n      # We specify the vertices in a numpy array.\n      beam_vertices = np.array([\n          [-1e6, -500., -500.],\n          [-1e6, 500., -500.],\n          [-1e6, 500., 500.],\n          [-1e6, -500., 500.],\n          [1e6, -500., -500.],\n          [1e6, 500., -500.],\n          [1e6, 500., 500.],\n          [1e6, -500., 500.]])\n\n      beam = Beam(\n          beam_vertices,\n          xray_propagation_direction=np.array([1., 0., 0.]),\n          wavelength=0.28523,\n          polarization_vector=np.array([0., 1., 0.]))\n\nWe will also need to define a detector:\n\n   .. code:: python\n\n      from xrd_simulator.detector import Detector\n      # The detector plane is defined by it's corner coordinates det_corner_0,det_corner_1,det_corner_2\n      detector = Detector(pixel_size_z=75.0,\n                          pixel_size_y=55.0,\n                          det_corner_0=np.array([142938.3, -38400., -38400.]),\n                          det_corner_1=np.array([142938.3, 38400., -38400.]),\n                          det_corner_2=np.array([142938.3, -38400., 38400.]))\n\nNext we go ahead and produce a sample, to do this we need to first define a mesh that\ndescribes the topology of the sample, in this example we make the sample shaped as a ball:\n\n   .. code:: python\n\n      from xrd_simulator.mesh import TetraMesh\n      # xrd_simulator supports several ways to generate a mesh, here we\n      # generate meshed solid sphere using a level set.\n      mesh = TetraMesh.generate_mesh_from_levelset(\n          level_set=lambda x: np.linalg.norm(x) - 768.0,\n          bounding_radius=769.0,\n          max_cell_circumradius=450.)\n\nEvery element in the sample is composed of some material, or \"phase\", we define the present phases\nin a list of ``xrd_simulator.phase.Phase`` objects, in this example only a single phase is present:\n\n   .. code:: python\n\n      from xrd_simulator.phase import Phase\n      quartz = Phase(unit_cell=[4.926, 4.926, 5.4189, 90., 90., 120.],\n                     sgname='P3221',  # (Quartz)\n                     path_to_cif_file=None  # phases can be defined from crystalographic information files\n                     )\n\nThe polycrystal sample can now be created. In this example the crystal elements have random orientations\nand the strain is uniformly zero in the sample:\n\n   .. code:: python\n\n      from scipy.spatial.transform import Rotation as R\n      from xrd_simulator.polycrystal import Polycrystal\n      orientation = R.random(mesh.number_of_elements).as_matrix()\n      polycrystal = Polycrystal(mesh,\n                                orientation,\n                                strain=np.zeros((3, 3)),\n                                phases=quartz,\n                                element_phase_map=None)\n\nWe may save the polycrystal to disc by using the builtin ``save()`` command as\n\n   .. code:: python\n\n      polycrystal.save('my_polycrystal', save_mesh_as_xdmf=True)\n\nWe can visualize the sample by loading the .xdmf file into your favorite 3D rendering program.\nIn `paraview`_ the sampled colored by one of its Euler angles looks like this:\n\n.. image:: https://github.com/FABLE-3DXRD/xrd_simulator/blob/main/docs/source/images/example_polycrystal_readme.png?raw=true\n   :align: center\n\nWe can now define some motion of the sample over which to integrate the diffraction signal:\n\n   .. code:: python\n\n      from xrd_simulator.motion import RigidBodyMotion\n      motion = RigidBodyMotion(rotation_axis=np.array([0, 1/np.sqrt(2), -1/np.sqrt(2)]),\n                               rotation_angle=np.radians(1.0),\n                               translation=np.array([123, -153.3, 3.42]))\n\nNow that we have an experimental setup we may collect diffraction by letting the beam and detector\ninteract with the sample:\n\n   .. code:: python\n\n      polycrystal.diffract(beam, detector, motion)\n      diffraction_pattern = detector.render(frames_to_render=0,\n                                              lorentz=False,\n                                              polarization=False,\n                                              structure_factor=False,\n                                              method=\"project\")\n\nThe resulting rendered detector frame will look something like the below. Note that the positions of the diffraction spots may vary as the crystal orientations were randomly generated!:\n\n   .. code:: python\n\n      import matplotlib.pyplot as plt\n      fig,ax = plt.subplots(1,1)\n      ax.imshow(diffraction_pattern, cmap='gray')\n      plt.show()\n\n.. image:: https://github.com/FABLE-3DXRD/xrd_simulator/blob/main/docs/source/images/diffraction_pattern.png?raw=true\n   :align: center\n\nTo compute several frames simply change the motion and collect the diffraction again. The sample may be moved before\neach computation using the same or another motion.\n\n   .. code:: python\n\n      polycrystal.transform(motion, time=1.0)\n      polycrystal.diffract(beam, detector, motion)\n\nMany more options for experimental setups and intensity rendering exist, have fun experimenting!\nThe above example code can be found as a `single .py file here.`_\n\n======================================\nInstallation\n======================================\n\nAnaconda installation (Linux and Macos)\n=============================================\n``xrd_simulator`` is distributed on the `conda-forge channel`_ and the preferred way to install\nthe xrd_simulator package is via `Anaconda`_::\n\n   conda create -n xrd_simulator\n   conda activate xrd_simulator\n   conda install -c conda-forge xrd_simulator\n\nThis is meant to work across OS-systems and requires an `Anaconda`_ installation.\n\n(The conda-forge feedstock of ``xrd_simulator`` `can be found here.`_)\n\nAnaconda installation (Windows)\n======================================\nTo install with anaconda on windows you must make sure that external dependencies of `pygalmesh`_ are preinstalled\non your system. Documentation on installing these package `can be found elsewhere.`_\n\nPip Installation\n======================================\nPip installation is possible, however, external dependencies of `pygalmesh`_ must the be preinstalled\non your system. Installation of these will be OS dependent and documentation\n`can be found elsewhere.`_::\n\n   pip install xrd-simulator\n\nSource installation\n===============================\nNaturally one may also install from the sources::\n\n   git clone https://github.com/FABLE-3DXRD/xrd_simulator.git\n   cd xrd_simulator\n   python setup.py install\n\nThis will then again require the `pygalmesh`_ dependencies to be resolved beforehand.\n\nCredits\n===============================\n``xrd_simulator`` makes good use of xfab and pygalmesh. The source code of these repos can be found here:\n\n* `https://github.com/FABLE-3DXRD/xfab`_\n* `https://github.com/nschloe/pygalmesh`_\n\nCitation\n===============================\nIf you feel that ``xrd_simulator`` was helpful in your research we would love for you to cite us.\n\n*xrd_simulator: 3D X-ray diffraction simulation software supporting 3D polycrystalline microstructure morphology descriptions\nHenningsson, A. \u0026 Hall, S. A. (2023). J. Appl. Cryst. 56, 282-292.*\n`https://doi.org/10.1107/S1600576722011001`_\n\n.. _https://doi.org/10.1107/S1600576722011001: https://doi.org/10.1107/S1600576722011001\n\n.. _https://github.com/FABLE-3DXRD/xfab: https://github.com/FABLE-3DXRD/xfab\n\n.. _https://github.com/marmakoide/miniball: https://github.com/marmakoide/miniball\n\n.. _Anaconda: https://www.anaconda.com/products/individual\n\n.. _pygalmesh: https://github.com/nschloe/pygalmesh\n\n.. _https://github.com/nschloe/pygalmesh: https://github.com/nschloe/pygalmesh\n\n.. _can be found elsewhere.: https://github.com/nschloe/pygalmesh#installation\n\n.. _scanning-3dxrd: https://doi.org/10.1107/S1600576720001016\n\n.. _3dxrd: https://en.wikipedia.org/wiki/3DXRD\n\n.. _powder like: https://en.wikipedia.org/wiki/Powder_diffraction\n\n.. _which is hosted here: https://FABLE-3DXRD.github.io/xrd_simulator/\n\n.. _which is hosted here: https://FABLE-3DXRD.github.io/xrd_simulator/\n\n.. _single .py file here.: https://github.com/FABLE-3DXRD/xrd_simulator/blob/main/docs/source/examples/readme_tutorial.py\n\n.. _paraview: https://www.paraview.org/\n\n.. _can be found here.: https://github.com/conda-forge/xrd_simulator-feedstock\n\n.. _conda-forge channel: https://anaconda.org/conda-forge/xrd_simulator\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffable-3dxrd%2Fxrd_simulator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffable-3dxrd%2Fxrd_simulator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffable-3dxrd%2Fxrd_simulator/lists"}