---
title: PyWPEM inputs and parameters
description: 'Pick one of 14 operations, then supply an XRD intensity CSV, a CIF by URL or inline text, a wavelength preset such as CuKa1Ka2, and the two-theta range.'
tags:
  - pywpem
  - inputs
---

You provide an operation along with XRD data, a CIF structure, or both. The `operation` you choose is what most affects the result, since it determines which of those inputs are required and how the pattern is processed.

## PyWPEM inputs and parameters

## Common parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `operation` | string | required | One of the 14 operation names above |
| `wavelength_preset` | string | `"CuKa1Ka2"` | X-ray source preset — see table below |
| `custom_wavelengths` | number[] | -- | Custom wavelength(s) in Å, used when `wavelength_preset` is `"custom"` |
| `two_theta_min` | number | `10` | Minimum 2-theta angle (degrees) |
| `two_theta_max` | number | `90` | Maximum 2-theta angle (degrees) |
| `two_theta_step` | number | `0.02` | Angular step size (degrees) |

Not every operation reads all of these — `wavelength_preset`/`custom_wavelengths` and the two-theta range mainly matter for `simulate_xrd`, `preprocess_cif`, and `fit_amorphous`.

### Wavelength presets (`wavelength_preset`)

| Preset key | Source | Wavelength (Å) |
|--------|----------------|-----|
| `CuKa1Ka2` | Cu K-alpha doublet (default, most common lab setup) | 1.5406 / 1.5444 |
| `CuKa` | Cu K-alpha (weighted average) | 1.5418 |
| `MoKa` | Mo K-alpha (single-crystal diffraction) | 0.7107 |
| `CoKa` | Co K-alpha (reduces fluorescence from Fe-containing samples) | 1.7902 |
| `FeKa` | Fe K-alpha | 1.9373 |
| `CrKa` | Cr K-alpha (stress analysis, texture) | 2.291 |
| `AgKa` | Ag K-alpha (high-energy, deep penetration) | 0.5594 |
| `custom` | User-defined — supply `custom_wavelengths` | -- |

## XRD data input

For operations requiring experimental data:

| Parameter | Type | Description |
|-----------|------|-------------|
| `xrd_data_url` | string | S3 URL to an XRD intensity CSV (`two_theta`, `intensity` columns) |

There is no inline/raw-text alternative for this field — upload the CSV and pass its URL.

## CIF structure input

For operations requiring crystal structure data:

| Parameter | Type | Description |
|-----------|------|-------------|
| `cif_url` | string | URL to a CIF file — from the [COD](https://crystallography.net/cod/) (`crystallography.net/cod/XXXXXXX.cif`), CCDC, ICDD, or S3. Do not use a PubChem 3D-conformer URL — it serves an HTML page, not a CIF file. |
| `cif_content` | string | Inline CIF file content (alternative to `cif_url`) |

### CIF requirements

- Must include `_cell_length_a/b/c` and `_cell_angle_alpha/beta/gamma`
- Must include `_atom_site_fract_x/y/z` coordinates
- Must include `_symmetry_space_group_name_H-M` or equivalent

## Operation-specific parameters

### fit_background

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `background_segments` | integer | `5` | Number of segments for piecewise background fitting |

### simulate_xrd

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `grain_size_nm` | number | -- | Crystallite grain size for peak broadening (nm, 5-100) |
| `replace_atom` | string | -- | Atom to replace for solid-solution simulation (e.g., `"Cu2+"`) |
| `substitute_atom` | string | -- | Substituting atom (e.g., `"Ti4+"`) |
| `substitution_ratio` | number | `0.1` | Fraction of atoms to replace (0-1) |

### refine_xrd

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `background_url` | string | -- | S3 URL to a background CSV (from `fit_background`) |
| `no_background_url` | string | -- | S3 URL to a background-subtracted CSV (from `fit_background`) |
| `variance` | number | -- | Background variance (from the `fit_background` result) |
| `phases` | array | required | Phases to refine — one or more objects with `name` (required), `cif_url`, and `fixed` (keep lattice fixed) |
| `max_iterations` | integer | `40` | Maximum refinement iterations |
| `beta` | number | `0.8` | Initial Lorentzian fraction in the pseudo-Voigt peak profile (0-1) |

### fit_amorphous

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `num_components` | integer | `1` | Number of Gaussian components for amorphous fitting |

### calculate_rdf

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `density_atoms_per_cc` | number | -- | Atomic density for RDF calculation (atoms per cubic cm) |
| `scattering_factor` | number | -- | Scattering factor for RDF normalization |
| `r_max` | number | `10` | Maximum radial distance for RDF (Å) |

### fit_xps

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `xps_data_url` | string | required | S3 URL to XPS intensity data (`binding_energy`, `intensity` columns) |
| `peaks` | array | required | Peaks to fit — objects with `atom`, `orbital`, and `binding_energy` (all required) |

### fit_exafs

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `xafs_data_url` | string | required | S3 URL to XAFS data (`energy`, `mu` columns) |
| `power` | number | `2` | k-weighting power for the EXAFS transform |
| `k_cutoff` | number | `12` | k-space cutoff for the Fourier transform (Å⁻¹) |
| `transform_type` | string | `"fourier"` | `"fourier"` or `"wavelet"` |

### generate_crystal_graph

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `graph_type` | string | `"connectivity"` | `"connectivity"` (bond-based, CGCNN/standard GNN), `"voronoi"` (dense/amorphous phases), or `"distance"` (MEGNet-style continuous edges) |
| `max_neighbors` | integer | `12` | Maximum neighbors per atom in the graph |
| `cutoff_distance` | number | `5.0` | Distance cutoff for neighbor search (Å) |

### search_substitutional_sites

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `target_element` | string | required | Element to substitute (e.g., `"Fe"`) |
| `substitute_element` | string | required | Substituting element (e.g., `"Co"`) |
| `energy_threshold` | number | `1.0` | Maximum formation energy threshold (eV) |

This operation requires `cif_url` specifically (not `cif_content`).

### plot_components

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `plot_type` | string | required | `"xrd"`, `"xps"`, `"exafs"`, `"rdf"`, or `"amorphous"` |
| `components` | integer[] | -- | Component indices to include in the plot |
| `show_residual` | boolean | `true` | Show the residual curve |
| `title` | string | -- | Custom plot title |

### convert_file_format

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `input_url` | string | required | S3 URL to the input file |
| `input_format` | string | required | `"csv"`, `"xy"`, `"xye"`, `"cif"`, `"json"`, `"raw"`, or `"brml"` |
| `output_format` | string | required | Same set of values as `input_format` |

### compute_graph_matrix

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `matrix_operation` | string | `"to_adjacency"` | `"to_matrix"`, `"to_adjacency"`, or `"laplacian"` |
| `normalize` | boolean | `false` | Normalize the matrix |

### split_ml_datasets

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `data_url` | string | -- | S3 URL to the dataset to split |
| `data_urls` | string[] | -- | Multiple S3 URLs to merge and split (alternative to `data_url`) |
| `train_ratio` | number | `0.8` | Fraction of data for the training set |
| `val_ratio` | number | `0.1` | Fraction of data for the validation set |
| `test_ratio` | number | `0.1` | Fraction of data for the test set |
| `stratify_column` | string | -- | Column name for stratified splitting |
| `random_seed` | integer | `42` | Random seed for reproducible splits |

## Input validation

- `operation` is always required; every other field is operation-dependent
- CIF files must parse without syntax errors
- `refine_xrd` requires at least one entry in `phases`
- `fit_xps` requires at least one entry in `peaks`, each with `atom`, `orbital`, and `binding_energy`

## Read next