User Guide

This comprehensive guide covers all aspects of using nbragg for neutron Bragg edge transmission analysis.

Contents:

• Basic Usage
  • Quick Example
  • Data Loading
  • Defining Materials
  • Creating Models
  • Fitting Data
  • Analyzing Results
  • Setting Parameter Values
  • Next Steps
• Grouped Data Fitting
  • Overview
  • Supported Data Structures
  • Loading Grouped Data
  • Fitting Grouped Data
  • Accessing Results
  • Visualizing Parameter Maps
  • Saving and Loading
  • Combining Datasets
  • Advanced Features
  • Best Practices
  • Common Patterns
  • See Also
• Model Parameters
  • Overview
  • Parameter Categories
  • Common Patterns
  • Parameter Bounds and Constraints
  • Troubleshooting
  • See Also
• Saving and Loading Fits
  • Quick Start
  • Key Features
  • Complete Examples
  • Advanced Usage
  • What Gets Saved?
  • Best Practices
  • Troubleshooting
  • API Reference
  • See Also
• Crystal Orientation in nBragg
  • Understanding Crystal Orientation
  • Quick Start
  • Why Orientation Matters
  • Coordinate System Convention
  • Documentation Structure
  • Getting Started
  • Common Use Cases
  • Key Concepts
  • Mathematical Framework
  • Next Steps
  • Additional Resources
  • Questions?
• Crystal Orientation in nBragg
  • Overview
  • Coordinate System Convention
  • Defining Crystal Orientation
  • Practical Examples
  • Mosaicity and Crystal Imperfections
  • Crystal Rotation for Alignment
  • Visualization and Interpretation
  • Key Points for Users
  • Further Reading
  • See Also
• Crystal Orientation Quick Reference
  • Coordinate System
  • Specifying Orientation
  • Common Orientations
  • Rotation for Alignment
  • Mosaicity Parameters
  • Bragg Condition
  • Troubleshooting Checklist
  • Quick Equations Reference
  • Best Practices
  • Code Snippets
  • Related Resources
  • Citation
• MTEX Integration
  • Overview
  • Quick Start
  • Material Specification
  • CSV Format
  • Orientation Representation
  • Phase Naming
  • Complete Example
  • Advanced Usage
  • Troubleshooting
  • Integration Checklist
  • See Also
• Advanced Fitting
  • Multi-Stage Refinement
  • Custom Stage Definitions
  • See Also

Quick Links

New to nbragg?

Start with Basic Usage to learn the fundamentals.

Analyzing grouped or spatially-resolved data?

See Grouped Data Fitting for 2D grids, 1D arrays, and multi-sample analysis.

Saving and loading fits?

See Saving and Loading Fits to learn how to save results and resume analysis sessions.

Working with oriented materials?

See the Crystal Orientation in nBragg for a complete guide to crystal orientations.

Importing MTEX data?

Check out MTEX Integration for seamless MTEX workflow integration.

Need advanced fitting control?

Explore Model Parameters and Advanced Fitting.

Overview

Core Concepts

Cross Sections

nbragg uses NCrystal to calculate neutron cross sections for crystalline materials. Learn how to define materials, handle multi-phase samples, and work with oriented crystals.

Transmission Models

The TransmissionModel class provides flexible fitting capabilities with multi-stage refinement strategies including true Rietveld refinement.

Parameter Control

Fine-grained control over which parameters vary during fitting, including basic parameters (thickness, norm), weights, orientations, and more.

Key Features

• Grouped/Gridded Data: Analyze spatially-resolved or multi-sample datasets with parallel fitting

• Multi-phase Analysis: Model powder and textured samples with multiple phases

• Oriented Materials: Full support for single crystal and textured polycrystals

• MTEX Integration: Import orientation distributions from MTEX for texture analysis

• Flexible Fitting: Rietveld and staged refinement strategies

• Parameter Management: Control all aspects of your fit with vary_* parameters

What’s New

Recent additions to nbragg include:

Grouped/Gridded Data Fitting

• Data.from_grouped() for loading spatially-resolved or multi-sample data

• Parallel fitting with n_jobs parameter

• plot_parameter_map() with auto-detection of plot type (heatmap/line/bar)

• Flexible indexing: tuples (0,0), strings "(0,0)", integers, or names

• GroupedFitResult with save(), load(), and fit_report() methods

• See Grouped Data Fitting for complete documentation

Save and Load Functionality

• result.save() method for easy saving of fit results

• TransmissionModel.load() automatically detects model or result files

• Initialize models directly from saved files: TransmissionModel("fit.json")

• Loaded results have all methods (plot, save, etc.)

• JSON-based format avoids ctypes pickle issues

• See Saving and Loading Fits for complete documentation

Model Parameter Control

• New vary_basic parameter to control thickness and norm fitting

• Automatic initialization of orientation parameters from material properties

• Temperature parameter now fixed by default

MTEX Integration Improvements

• from_mtex() now accepts material as string or dictionary

• Automatic short_name generation from material filenames

• Better handling of powder phases in oriented materials

Enhanced Documentation

• Comprehensive save/load guide

• Crystal orientation guide

• Quick reference cards for common operations

• Executable examples for all major features

Getting Help

• Quickstart - Get started quickly

• API Reference - Complete API reference

• Iron Powder Example - Working examples

• GitHub Issues - Report bugs or request features