Repository files navigation

TheX-R ayD iffractionSIMULATOR package defines polycrystals as a mesh of tetrahedral single crystalsand simulates diffraction as collected by a 2D discretized detector array while the sample is rockedaround an arbitrary rotation axis. The full journal paper associated to the release of this code can be found here:

xrd_simulator: 3D X-ray diffraction simulation software supporting 3D polycrystalline microstructure morphology descriptionsHenningsson, A. & Hall, S. A. (2023). J. Appl. Cryst. 56, 282-292.https://doi.org/10.1107/S1600576722011001

xrd_simulator was originally developed with the hope to answer questions about measurement optimization inscanning x-ray diffraction experiments. However,xrd_simulator can simulate a wide range of experimentaldiffraction setups. The essential idea is that the sample and beam topology can be arbitrarily specified,and their interaction simulated as the sample is rocked. This means that standard "non-powder" experimentssuch asscanning-3dxrd and full-field3dxrd (or HEDM if you like) can be simulated as well as more advancedmeasurement sequences such as helical scans for instance. It is also possible to simulatepowder likescenarios using orientation density functions as input.

Before reading all the boring documentation (which is hosted here) let's dive into some end to endexamples to get us started on a good flavour.

Thexrd_simulator is built around four python objects which reflect a diffraction experiment:

• Abeam of x-rays (using thexrd_simulator.beam module)
• A 2D areadetector (using thexrd_simulator.detector module)
• A 3Dpolycrystal sample (using thexrd_simulator.polycrystal module)
• A rigid body samplemotion (using thexrd_simulator.motion module)

Once these objects are defined it is possible to let thedetector collect scattering of thepolycrystalas the sample undergoes the prescribed rigid bodymotion while being illuminated by the xraybeam.

Let's go ahead and build ourselves some x-rays:

importnumpyasnpfromxrd_simulator.beamimportBeam# The beam of xrays is represented as a convex polyhedron# We specify the vertices in a numpy array.beam_vertices=np.array([    [-1e6,-500.,-500.],    [-1e6,500.,-500.],    [-1e6,500.,500.],    [-1e6,-500.,500.],    [1e6,-500.,-500.],    [1e6,500.,-500.],    [1e6,500.,500.],    [1e6,-500.,500.]])beam=Beam(beam_vertices,xray_propagation_direction=np.array([1.,0.,0.]),wavelength=0.28523,polarization_vector=np.array([0.,1.,0.]))

We will also need to define a detector:

fromxrd_simulator.detectorimportDetector# The detector plane is defined by it's corner coordinates det_corner_0,det_corner_1,det_corner_2detector=Detector(pixel_size_z=75.0,pixel_size_y=55.0,det_corner_0=np.array([142938.3,-38400.,-38400.]),det_corner_1=np.array([142938.3,38400.,-38400.]),det_corner_2=np.array([142938.3,-38400.,38400.]))

Next we go ahead and produce a sample, to do this we need to first define a mesh thatdescribes the topology of the sample, in this example we make the sample shaped as a ball:

fromxrd_simulator.meshimportTetraMesh# xrd_simulator supports several ways to generate a mesh, here we# generate meshed solid sphere using a level set.mesh=TetraMesh.generate_mesh_from_levelset(level_set=lambdax:np.linalg.norm(x)-768.0,bounding_radius=769.0,max_cell_circumradius=450.)

Every element in the sample is composed of some material, or "phase", we define the present phasesin a list ofxrd_simulator.phase.Phase objects, in this example only a single phase is present:

fromxrd_simulator.phaseimportPhasequartz=Phase(unit_cell=[4.926,4.926,5.4189,90.,90.,120.],sgname='P3221',# (Quartz)path_to_cif_file=None# phases can be defined from crystalographic information files               )

The polycrystal sample can now be created. In this example the crystal elements have random orientationsand the strain is uniformly zero in the sample:

fromscipy.spatial.transformimportRotationasRfromxrd_simulator.polycrystalimportPolycrystalorientation=R.random(mesh.number_of_elements).as_matrix()polycrystal=Polycrystal(mesh,orientation,strain=np.zeros((3,3)),phases=quartz,element_phase_map=None)

We may save the polycrystal to disc by using the builtinsave() command as

polycrystal.save('my_polycrystal',save_mesh_as_xdmf=True)

We can visualize the sample by loading the .xdmf file into your favorite 3D rendering program.Inparaview the sampled colored by one of its Euler angles looks like this:

We can now define some motion of the sample over which to integrate the diffraction signal:

fromxrd_simulator.motionimportRigidBodyMotionmotion=RigidBodyMotion(rotation_axis=np.array([0,1/np.sqrt(2),-1/np.sqrt(2)]),rotation_angle=np.radians(1.0),translation=np.array([123,-153.3,3.42]))

Now that we have an experimental setup we may collect diffraction by letting the beam and detectorinteract with the sample:

polycrystal.diffract(beam,detector,motion)diffraction_pattern=detector.render(frames_to_render=0,lorentz=False,polarization=False,structure_factor=False,method="project")

The 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!:

importmatplotlib.pyplotaspltfig,ax=plt.subplots(1,1)ax.imshow(diffraction_pattern,cmap='gray')plt.show()

To compute several frames simply change the motion and collect the diffraction again. The sample may be moved beforeeach computation using the same or another motion.

polycrystal.transform(motion,time=1.0)polycrystal.diffract(beam,detector,motion)

Many more options for experimental setups and intensity rendering exist, have fun experimenting!The above example code can be found as asingle .py file here.

xrd_simulator is distributed on theconda-forge channel and the preferred way to installthe xrd_simulator package is viaAnaconda:

conda create -n xrd_simulatorconda activate xrd_simulatorconda install -c conda-forge xrd_simulator

This is meant to work across OS-systems and requires anAnaconda installation.

(The conda-forge feedstock ofxrd_simulatorcan be found here.)

To install with anaconda on windows you must make sure that external dependencies ofpygalmesh are preinstalledon your system. Documentation on installing these packagecan be found elsewhere.

Pip installation is possible, however, external dependencies ofpygalmesh must the be preinstalledon your system. Installation of these will be OS dependent and documentationcan be found elsewhere.:

pip install xrd-simulator

Naturally one may also install from the sources:

git clone https://github.com/FABLE-3DXRD/xrd_simulator.gitcd xrd_simulatorpython setup.py install

This will then again require thepygalmesh dependencies to be resolved beforehand.

xrd_simulator makes good use of xfab and pygalmesh. The source code of these repos can be found here:

• https://github.com/FABLE-3DXRD/xfab
• https://github.com/nschloe/pygalmesh

If you feel thatxrd_simulator was helpful in your research we would love for you to cite us.

xrd_simulator: 3D X-ray diffraction simulation software supporting 3D polycrystalline microstructure morphology descriptionsHenningsson, A. & Hall, S. A. (2023). J. Appl. Cryst. 56, 282-292.https://doi.org/10.1107/S1600576722011001