Tutorial on nano crystal diffraction

CrystFELPhotonDiffractor example

---

Introduction

In this example, we demonstrate how to use the CrystFELPhotonDiffractor and related classes to setup, execute, and diagnose simulation of XFEL photons diffracting from a nano-crystalline sample using the CrystFEL.pattern_sim backengine.

Setup

To setup the simulation, we need to specify the photon beam and the sample.

Photon Beam

The photon beam can be parametrized using the PhotonBeamParameters object or by giving a wavefront file as input_path parameter to the CrystFELPhotonDiffractor. In this example, we will first discuss the beam parametrization, as it allows much faster simulations, and explain howto use a wavefront file, afterwards.

The following snippet shows how to use the PhotonBeamParameters object:

# Import needed Calculators and Parameters
from SimEx import *

beam = PhotonBeamParameters(
    photon_energy = 4972.0 * electronvolt,  # photon energy in eV
    beam_diameter_fwhm=1.3e-7 * meter,      # focus diameter in m
    pulse_energy=0.45e-3 * joule,           # pulse energy in J
    photon_energy_relative_bandwidth=0.003, # relative bandwidth dE/E
    divergence=0.0 * radian,                # Beam divergence in rad
    photon_energy_spectrum_type='tophat',   # Spectrum type. Acceptable values are "tophat", "SASE", and "twocolor")
    )

Alternatively, we can create a PhotonBeamParameters instance using the utility function propToBeamParameters:

beams = SimEx.Parameters.PhotonBeamParameters.propToBeamParameters("prop_out_0000001.h5")

This would extract all parameters needed to setup the PhotonBeamParameters instance from the wavefront data. The diffraction simulation will take much longer time, in this case, as the entrire SASE spectrum would be sampled in up to 512 equidistant frequency (energy) steps. For quick tests, consider setting the spectrum type to "tophat":

beams.photon_energy_spectrum_type = 'tophat'

which would create a tophat spectrum with the relative bandwidth extracted from the wavefront file.

Diffraction Parameters

Next, we setup the parameters for the diffraction calculation using the CrystFELPhotonDiffractorParameters object:

parameters = CrystFELPhotonDiffractorParameters(
    sample='5udc.pdb',                    # Looks up pdb file in cwd, if not found, queries from RCSB pdb mirror.
    uniform_rotation=True,                # Apply random rotation
    number_of_diffraction_patterns=1,     #
    powder=False,                         # Set to True to create a virtual powder diffraction pattern (unested) 
    intensities_file=None,                # File that contains reflection intensities. If set to none, use uniform intensity distribution
    crystal_size_range=[1e-7,1e-7],       # Range ([min,max]) in units of metres of crystal size.
    poissonize=False,                     # Set to True to add Poisson noise.
    number_of_background_photons=0,       # Change number to add uniformly distributed background photons.
    suppress_fringes=False,               # Set to True to suppress side maxima between reflection peaks.
    beam_parameters=beam,                 # Beam parameters object from above
    detector_geometry='simple.geom',      # External file that contains the detector geometry in CrystFEL notation.
    )

The geometry file can be copied from this link. It originates from the CrystFEL share directory.

Diffractor setup and execution

We're now in good shape to create the CrystFELPhotonDiffractor itself using the canonical syntax common to all Calculators:

diffractor = CrystFELPhotonDiffractor(
    parameters=parameters,      
    output_path="xstal_diffr")  # Output will go to a new dir "xstal_diffr/" in the current directory.

and launch the calculation with

error = diffractor.backengine()

Finally, we want to reformat the pattern_sim output to make the results readable from simex_platform's diagnostic utilities:

error = diffractor.saveH5() # Creates a new file "xstal_diffr.ht" in the CWD and links in the datasets from "xstal_diffr/*.h5

Now, we can visualize the diffraction pattern using the diffr_diagnostics CLI:

$> diffr_diagnostics.py -P -p1 -z True xstal_diffr.h5

which should produce a figure similar to this one:

Finally, for the impatient, here's the link to the entire script .