diffpy.morph/tutorials.html at gh-pages · diffpy/diffpy.morph

History

390 lines (369 loc) · 30.2 KB

Raw

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

312

313

314

315

316

317

318

319

320

321

322

323

324

325

326

327

328

329

330

331

332

333

334

335

336

337

338

339

340

341

342

343

344

345

346

347

348

349

350

351

352

353

354

355

356

357

358

359

360

361

362

363

364

365

366

367

368

369

370

371

372

373

374

375

376

377

378

379

380

381

382

383

384

385

386

387

388

389

390

<!DOCTYPE html>

<head>

<title>Advanced Tutorials — diffpy.morph 0.0.1 documentation</title>

</head>

diffpy.morph

</a>

</form>

</div>

</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">

<li class="toctree-l1"><a class="reference internal" href="quickstart.html">Quickstart</a></li>

<li class="toctree-l1 current"><a class="current reference internal" href="#">Advanced Tutorials</a></li>

<li class="toctree-l1"><a class="reference internal" href="morphpy.html">Using diffpy.morph in Python</a></li>

<li class="toctree-l1"><a class="reference internal" href="license.html">License</a></li>

<li class="toctree-l1"><a class="reference internal" href="release.html">Release notes</a></li>

<li class="toctree-l1"><a class="reference internal" href="api/diffpy.morph.html">Package API</a></li>

</ul>

</div>

</nav>

<a href="index.html">diffpy.morph</a>

</nav>

<li class="breadcrumb-item active">Advanced Tutorials</li>

<a href="https://github.com/diffpy/diffpy.morph/blob/main/doc/source/tutorials.rst" class="fa fa-github"> Edit on GitHub</a>

</li>

</ul>

<hr/>

</div>

<h1>Advanced Tutorials<a class="headerlink" href="#advanced-tutorials" title="Link to this heading"></a></h1>

<code class="docutils literal notranslate">diffpy.morph</code> has some more functionalities not showcased in the <a class="reference external" href="quickstart.html">quickstart tutorial</a>.

Tutorials for these are included below. The files required for these tutorials can be downloaded

<a class="reference download internal" download="" href="_downloads/8dd70104405f43d31c22866f684b6a94/additionalData.zip"><code class="xref download docutils literal notranslate">here</code></a>.

For a full list of options offered by <code class="docutils literal notranslate">diffpy.morph</code>, please run <code class="docutils literal notranslate">diffpy.morph --help</code> on the command line.

<h2>Using MorphFuncxy<a class="headerlink" href="#using-morphfuncxy" title="Link to this heading"></a></h2>

Examples of how to use the general morph <code class="docutils literal notranslate">MorphFuncxy</code> with commonly used

diffraction software like <a class="reference external" href="https://www.diffpy.org/products/pdfgetx.html">PDFgetx3</a>

and <a class="reference external" href="https://pyfai.readthedocs.io/en/stable/">PyFai</a> are directed to the

<a class="reference external" href="funcxy.html">funcxy tutorials</a>.

</section>

<h2>Performing Multiple Morphs<a class="headerlink" href="#performing-multiple-morphs" title="Link to this heading"></a></h2>

It may be useful to morph a PDF against multiple targets:

for example, you may want to morph a PDF against multiple PDFs measured

at various temperatures to determine whether a phase change has occurred.

<code class="docutils literal notranslate">diffpy.morph</code> currently allows users to morph a PDF against all files in a

selected directory and plot resulting \(R_w\) values from each morph.

<li>Within the <code class="docutils literal notranslate">additionalData</code> directory, <code class="docutils literal notranslate">cd</code> into the

<code class="docutils literal notranslate">morphsequence</code> directory. Inside, you will find multiple PDFs of

\(SrFe_2As_2\) measured at various temperatures. These PDFs are

from <a class="reference external" href="https://global.oup.com/academic/product/atomic-pair-distribution-function-analysis-9780198885801">“Atomic Pair Distribution Function Analysis: A primer”</a>.</li>

<li>Let us start by getting the \(R_w\) of <code class="docutils literal notranslate">SrFe2As2_150K.gr</code> compared to

all other files in the directory. Run

</pre></div>

</div>

The multiple tag indicates we are comparing PDF file (first input)

against all PDFs in a directory (second input). Our choice of file

was <code class="docutils literal notranslate">SeFe2As2_150K.gr</code> and directory was the cwd, which should be

<code class="docutils literal notranslate">morphsequence</code>.

</li>

</ol>

Bar chart of \(R_W\) values for each target file. Target files are

listed in ASCII sort order.<a class="headerlink" href="#id2" title="Link to this image"></a>

</figcaption>

</figure>

<li>After running this, we get chart of \(R_w\) values for each target file.

However, this chart can be a bit confusing to interpret. To get a

more understandable plot, run

</pre></div>

</div>

This plots the \(R_w\) against the temperature parameter value provided

at the top of each file. Parameters are entries of the form

<code class="docutils literal notranslate"><parameter_name> = <parameter_value></code> and are located above

the <code class="docutils literal notranslate">r</code> versus <code class="docutils literal notranslate">gr</code> table in each PDF file.

<div class="highlight-default notranslate"><div class="highlight"><pre># SrFe2As2_150K.gr

[PDF Parameters]

temperature = 150

wavelength = 0.1

...

</pre></div>

</div>

</li>

</ol>

The \(R_W\) plotted against the temperature the target PDF was

measured at.<a class="headerlink" href="#id3" title="Link to this image"></a>

</figcaption>

</figure>

<li>Between 192K and 198K, the Rw has a sharp increase, indicating that

we may have a phase change. To confirm, let us now apply morphs

onto <code class="docutils literal notranslate">SrFe2As2_150K.gr</code> with all other files in

<code class="docutils literal notranslate">morphsequence</code> as targets

<div class="highlight-default notranslate"><div class="highlight"><pre>diffpy.morph --scale=1 --stretch=0 SrFe2As2_150K.gr . --multiple-targets --sort-by=temperature

</pre></div>

</div>

Note that we are not applying a smear since it takes a long time to

apply and does not significantly change the Rw values in this example.

</li>

<li>We should now see a sharper increase in \(R_w\) between 192K and 198K.</li>

<li>Go back to the terminal to see optimized morphing parameters from each morph.</li>

<li>On the morph with <code class="docutils literal notranslate">SrFe2As2_192K.gr</code> as target, <code class="docutils literal notranslate">scale =

0.972085</code> and <code class="docutils literal notranslate">stretch = 0.000508</code> and with <code class="docutils literal notranslate">SrFe2As2_198K.gr</code>

as target, <code class="docutils literal notranslate">scale = 0.970276</code> and <code class="docutils literal notranslate">stretch = 0.000510</code>. These

are very similar, meaning that thermal lattice expansion (accounted

for by <code class="docutils literal notranslate">stretch</code>) is not occurring. This, coupled with the fact

that the Rw significantly increases suggests a phase change in this

temperature regime. (In fact, \(SrFe_2As_2\) does transition

from orthorhombic at lower temperature to tetragonal at higher

temperature!). More sophisticated analysis can be done with

<a class="reference external" href="https://www.diffpy.org/products/pdfgui.html">PDFgui</a>.</li>

<li>Finally, let us save all the morphed PDFs into a directory

named <code class="docutils literal notranslate">saved-morphs</code>.

<div class="highlight-default notranslate"><div class="highlight"><pre>diffpy.morph SrFe2As2_150K.gr . --scale=1 --stretch=0 --multiple-targets \

--sort-by=temperature --plot-parameter=stretch \

--save=saved-morphs

</pre></div>

</div>

Entering the directory with <code class="docutils literal notranslate">cd</code> and viewing its contents with

<code class="docutils literal notranslate">ls</code>, we see a file named <code class="docutils literal notranslate">morph-reference-table.txt</code> with data

about the input morph parameters and re- fined output parameters

and a directory named <code class="docutils literal notranslate">morphs</code> containing all the morphed

PDFs. See the <code class="docutils literal notranslate">--save-names-file</code> option to see how you can set

the names for these saved morphs!

</li>

</ol>

</section>

<h2>Polynomial Squeeze Morph<a class="headerlink" href="#polynomial-squeeze-morph" title="Link to this heading"></a></h2>

Another advanced feature in <code class="docutils literal notranslate">diffpy.morph</code> is the <code class="docutils literal notranslate">MorphSqueeze</code> morph,

which applies a user-defined polynomial to squeeze the morph function along the

x-axis. This provides a flexible way to correct for higher-order distortions

that simple shift or stretch morphs cannot fully address.

Such distortions can arise from geometric artifacts in X-ray detector modules,

including tilts, curved detection planes, or angle-dependent offsets, as well

as from intrinsic structural effects in the sample.

A first-order squeeze polynomial recovers the behavior of simple shift or stretch,

while higher-order terms enable non-linear corrections. The squeeze transformation

is defined as:

\[\Delta r(r) = a_0 + a_1 r + a_2 r^2 + \dots + a_n r^n\]</div>

where \(a_0, a_1, ..., a_n\) are the polynomial coefficients defined by the user.

In this example, we show how to apply a squeeze morph in combination

with a scale morph to match a morph function to its target. The required

files can be found in <code class="docutils literal notranslate">additionalData/morphsqueeze/</code>.

<li><code class="docutils literal notranslate">cd</code> into the <code class="docutils literal notranslate">morphsqueeze</code> directory:

<div class="highlight-default notranslate"><div class="highlight"><pre>cd additionalData/morphsqueeze

</pre></div>

</div>

Here you will find:

<li><code class="docutils literal notranslate">squeeze_morph.cgr</code> — the morph function with a small built-in polynomial distortion.</li>

<li><code class="docutils literal notranslate">squeeze_target.cgr</code> — the target function.</li>

</ul>

</li>

<li>Suppose we know that the morph needs a quadratic and cubic squeeze,

plus a scale factor to best match the target. As an initial guess,

we can use:

<li><code class="docutils literal notranslate">squeeze = 0,-0.001,-0.0001,0.0001</code>

(for a polynomial: \(a_0 + a_1 x + a_2 x^2 + a_3 x^3\))</li>

<li><code class="docutils literal notranslate">scale = 1.1</code></li>

</ul>

The squeeze polynomial is provided as a comma-separated list (no spaces):

<div class="highlight-default notranslate"><div class="highlight"><pre>diffpy.morph --scale=1.1 --squeeze=0,-0.001,-0.0001,0.0001 -a squeeze_morph.cgr squeeze_target.cgr

</pre></div>

</div>

</li>

<li><code class="docutils literal notranslate">diffpy.morph</code> will apply the polynomial squeeze and scale,

display the initial and refined coefficients, and show the final

difference <code class="docutils literal notranslate">Rw</code>.

To refine the squeeze polynomial and scale automatically, remove

the <code class="docutils literal notranslate">-a</code> tag if you used it. For example:

<div class="highlight-default notranslate"><div class="highlight"><pre>diffpy.morph --scale=1.1 --squeeze=0,-0.001,-0.0001,0.0001 squeeze_morph.cgr squeeze_target.cgr

</pre></div>

</div>

</li>

<li>Check the output for the final squeeze polynomial coefficients and scale.

They should match the true values used to generate the test data:

<li><code class="docutils literal notranslate">squeeze = 0, 0.01, 0.0001, 0.001</code></li>

<li><code class="docutils literal notranslate">scale = 0.5</code></li>

</ul>

<code class="docutils literal notranslate">diffpy.morph</code> refines the coefficients to minimize the residual

between the squeezed, scaled morph function and the target.

</li>

</ol>

Warning

Extrapolation risk:

A polynomial squeeze can shift morph data outside the target’s grid

(<code class="docutils literal notranslate">x</code>-axis) range,

so parts of the output may be extrapolated.

This is generally fine if the polynomial coefficients are small and

the distortion is therefore small. If your coefficients are large, check the

plots carefully — strong extrapolation can produce unrealistic features at

the edges. If needed, adjust the coefficients to keep the morph physically

meaningful.

</div>

Experiment with your own squeeze polynomials to fine-tune your morphs — even

small higher-order corrections can make a big difference!

</section>

<h2>Nanoparticle Shape Effects<a class="headerlink" href="#nanoparticle-shape-effects" title="Link to this heading"></a></h2>

A nanoparticle’s finite size and shape can affect the shape of its PDF.

We can use <code class="docutils literal notranslate">diffpy.morph</code> to morph a bulk material PDF to simulate these shape effects.

Currently, the supported nanoparticle shapes include: spheres and spheroids.

<ul>

<code class="docutils literal notranslate">morphShape</code> subdirectory. Inside, you will find a sample Ni bulk

material PDF <code class="docutils literal notranslate">Ni_bulk.gr</code>. This PDF is from

<a class="reference external" href="https://global.oup.com/academic/product/atomic-pair-distribution-function-analysis-9780198885801">“Atomic Pair Distribution Function Analysis: A primer”</a>.

There are also multiple <code class="docutils literal notranslate">.cgr</code> files with calculated Ni nanoparticle PDFs.</li>

<li>Let us apply various shape effect morphs on the bulk material to

reproduce these calculated PDFs.

<dt>Spherical Shape</dt><dd><ol class="arabic">

<li>The <code class="docutils literal notranslate">Ni_nano_sphere.cgr</code> file contains a generated

spherical nanoparticle with unknown radius. First, let us

plot <code class="docutils literal notranslate">Ni_blk.gr</code> against <code class="docutils literal notranslate">Ni_nano_sphere.cgr</code>

</pre></div>

</div>

Despite the two being the same material, the Rw is quite large.

To reduce the Rw, we will apply spherical shape effects onto the PDF.

However, in order to do so, we first need the radius of the

spherical nanoparticle.

</li>

<li>To get the radius, we can first observe a plot of

<code class="docutils literal notranslate">Ni_nano_sphere.cgr</code>

</pre></div>

</div>

Nanoparticles tend to have broader peaks at r-values larger

than the particle size, corresponding to the much weaker

correlations between molecules. On our plot, beyond r=22.5,

peaks are too broad to be visible, indicating our particle

size to be about 22.4. The approximate radius of a sphere

would be half of that, or 11.2.

</li>

<li>Now, we are ready to perform a morph applying spherical

effects. To do so, we use the <code class="docutils literal notranslate">--radius</code> parameter

<div class="highlight-default notranslate"><div class="highlight"><pre>diffpy.morph Ni_bulk.gr Ni_nano_sphere.cgr --radius=11.2 -a --xmax=30

</pre></div>

</div>

</li>

<li>We can see that the \(Rw\) value has significantly decreased

from before. Run without the <code class="docutils literal notranslate">-a</code> tag to refine

</pre></div>

</div>

</li>

<li>After refining, we see the actual radius of the

nanoparticle was closer to 12.</li>

</ol>

</dd>

</dl>

</li>

<li>Spheroidal Shape

<li>The <code class="docutils literal notranslate">Ni_nano_spheroid.cgr</code> file contains a calculated

spheroidal Ni nanoparticle. Again, we can begin by plotting

the bulk material against our nanoparticle

</pre></div>

</div>

</li>

<li>Inside the <code class="docutils literal notranslate">Ni_nano_spheroid.cgr</code> file, we are given that

the equatorial radius is 12 and polar radius is 6. This is

enough information to define our spheroid. To apply

spheroid shape effects onto our bulk, run

<div class="highlight-default notranslate"><div class="highlight"><pre>diffpy.morph Ni_bulk.gr Ni_nano_spheroid.cgr --radius=12 --pradius=6 -a --xmax=30

</pre></div>

</div>

Note that the equatorial radius corresponds to the

<code class="docutils literal notranslate">--radius</code> parameter and polar radius to <code class="docutils literal notranslate">--pradius</code>.

</li>

<li>Remove the <code class="docutils literal notranslate">-a</code> tag to refine.</li>

</ol>

</div></blockquote>

</li>

</ul>

</div></blockquote>

</li>

</ul>

There is also support for morphing from a nanoparticle to a bulk. When

applying the inverse morphs, it is recommended to set <code class="docutils literal notranslate">--xmax=psize</code>

where <code class="docutils literal notranslate">psize</code> is the longest diameter of the nanoparticle.

</section>

</div>

<a href="quickstart.html" class="btn btn-neutral float-left" title="Quickstart" accesskey="p" rel="prev"> Previous</a>

</div>

<hr/>

</div>

Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a

<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>

provided by <a href="https://readthedocs.org">Read the Docs</a>.

</footer>

</div>

</section>

</div>

jQuery(function () {

SphinxRtdTheme.Navigation.enable(true);

});

</script>

</body>

</html>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FilesExpand file tree

tutorials.html

Latest commit

History

tutorials.html

File metadata and controls