pdfbl.sequential package

Automated sequential refinements of PDF data.

pdfbl.sequential.pdfadapter module

class pdfbl.sequential.pdfadapter.PDFAdapter

Bases: object

Adapter to expose PDF fitting interface. Designed to provide a simplified PDF fitting interface for human users and AI agents.

recipe

The FitRecipe object managing the fitting process.

Type:

FitRecipe

initialize_profile(profile_path, qmin=None, qmax=None, xmin=None, xmax=None, dx=None)

Load and initialize the PDF profile from the given file path with some optional parameters.

initialize_structures(structure_paths: list[str], run_parallel=True)

Load and initialize the structures from the given file paths, and generate corresponding PDFGenerator objects.

initialize_contribution(equation_string=None)

Initialize the FitContribution object combining the PDF generators and the profile.

initialize_recipe()

Initialize the FitRecipe object for the fitting process.

set_initial_variable_values(variable_name_to_value: dict)

Update parameter values from the provided dictionary.

refine_variables(variable_names: list[str])

Refine the parameters specified in the list and in that order.

get_variable_names()

Get the names of all variables in the recipe.

save_results(mode: str, filename: str = None)

Save the fitting results.

get_variable_names() → list[str]

Get the names of all variables in the recipe.

Returns:

A list of variable names.

Return type:

list of str

initialize_contribution(equation_string=None)

Initialize the FitContribution object combining the PDF generators and the profile.

The target output, FitRecipe, requires a profile object, multiple PDFGenerator objects, and a FitContribution object combining them. This method creates the FitContribution object combining the profile and PDF generators.

Must be called after initialize_profile and initialize_structures.

Parameters:

equation_string (str) – The equation string defining the contribution. The default equation will be generated based on the number of phases. e.g. for one phase: “s0*G1”, for two phases: “s0*(s1*G1+(1-s1)*G2)”, for three phases: “s0*(s1*G1+s2*G2+(1-(s1+s2))*G3)”, …

Notes

Planned features:

• Support registerFunction for custom equations.

initialize_profile(profile_path: str, qmin=None, qmax=None, xmin=None, xmax=None, dx=None)

Load and initialize the PDF profile from the given file path with some optional parameters.

The target output, FitRecipe, requires a profile object, multiple PDFGenerator objects, and a FitContribution object combining them. This method initializes the profile object.

Parameters:

• profile_path (str) – The path to the experimental PDF profile file.

• qmin (float) – The minimum Q value for PDF calculation. The default value is the one parsed from the profile file.

• qmax (float) – The maximum Q value for PDF calculation. The default value is the one parsed from the profile file.

• xmin (float) – The minimum r value for PDF calculation. The default value is the one parsed from the profile file.

• xmax (float) – The maximum r value for PDF calculation. The default value is the one parsed from the profile file.

• dx (float) – The r step size for PDF calculation. The default value is the one parsed from the profile file.

initialize_recipe()

Initialize the FitRecipe object for the fitting process.

The target output, FitRecipe, requires a profile object, multiple PDFGenerator objects, and a FitContribution object combining them. This method creates the FitRecipe object combining the profile, PDF generators, and contribution.

Must be called after initialize_contribution.

Notes

Planned features:

• support instructions to

  • add variables

  • constrain variables of the scatters

  • change symmetry constraints

initialize_structures(structure_paths: list[str], run_parallel=True)

Load and initialize the structures from the given file paths, and generate corresponding PDFGenerator objects.

The target output, FitRecipe, requires a profile object, multiple PDFGenerator objects, and a FitContribution object combining them. This method creates the PDFGenerator objects from the structure files.

Must be called after initialize_profile.

Parameters:

structure_paths (list of str) – The list of paths to the structure files (CIF format).

Notes

Planned features:

• Support cif file manipulation.

  • Add/Remove atoms.

  • symmetry operations?

monitor_intermediate_results(key: str, step: int = 10, queue: Queue = None)

Store an intermediate result during the fitting process.

Parameters:

• key (str) – The key to identify the intermediate result.

• step (int) – The step interval to store the intermediate result.

• queue (Queue) – The queue to store the intermediate results.

refine_variables(variable_names: list[str])

Refine the parameters specified in the list and in that order. Must be called after initialize_recipe.

Parameters:

variable_names (list of str) – The names of the variables to refine.

residual(p=[])

Wrapper for the recipe residual function to store intermediate results if needed.

Parameters:

p (list) – List of parameter values.

Returns:

The residual array.

Return type:

numpy.ndarray

save_results(mode: Literal['str', 'dict'] = 'str', filename=None)

Save the fitting results. Must be called after refine_variables.

Parameters:

• mode (str) –

  The format to save the results. Options are:

  ”str” - Save results as a formatted text string. “dict” - Save results as a JSON-compatible dictionary.

• filename (str) – The path to the output file. If None, results will not be saved to a file.

Returns:

The fitting results in the specified format.

Return type:

str or dict

set_initial_variable_values(variable_name_to_value: dict)

Update parameter values from the provided dictionary.

Parameters:

variable_name_to_value (dict) – A dictionary mapping variable names to their new values.

pdfbl.sequential.sequential_cmi_runner module

class pdfbl.sequential.sequential_cmi_runner.SequentialCMIRunner

Bases: object

load_inputs(input_data_dir, structure_path, output_result_dir='results', filename_order_pattern='(\\d+)K\\.gr', whether_plot_y=False, whether_plot_ycalc=False, plot_variable_names=None, plot_result_names=None, plot_intermediate_result_names=None, refinable_variable_names=None, initial_variable_values=None, xmin=None, xmax=None, dx=None, qmin=None, qmax=None, show_plot=True)

Load and validate input configuration for sequential PDF refinement.

This method initializes the sequential CMI runner with input data, structure information, and refinement parameters, and the plotting configuration.

Parameters:

• input_data_dir (str) – The path to the directory containing input PDF profile files.

• structure_path (str) – The path to the structure file (e.g., CIF format) used for refinement.

• output_result_dir (str) – The path to the directory for storing refinement results. Default is “results”.

• filename_order_pattern (str) – The regular expression pattern to extract ordering information from filenames. Default is r”(d+)K.gr” to extract temperature values from filenames.

• refinable_variable_names (list of str) – The list of variable names to refine. Must exist in the recipe. Default variable names are all possible variables that can be created from the input structure and profile.

• initial_variable_values (dict) – The dictionary mapping variable names to their initial values. Default is None.

• xmin (float) – The minimum x-value for the PDF profile. Default is the value parsed from the input file.

• xmax (float) – The maximum x-value for the PDF profile. Default is the value parsed from the input file.

• dx (float) – The step size for the PDF profile. Default is the value parsed from the input file.

• qmin (float) – The minimum q-value for the PDF profile. Default is the value parsed from the input file.

• qmax (float) – The maximum q-value for the PDF profile. Default is the value parsed from the input file.

• show_plot (bool) – Whether to display plots during refinement. Default is True.

• whether_plot_y (bool) – Whether to plot the experimental PDF data (y). Default is False.

• whether_plot_ycalc (bool) – Whether to plot the calculated PDF data (ycalc). Default is False.

• plot_variable_names (list of str) – The list of variable names to plot during refinement. Default is None.

• plot_result_names (list of str) – The list of fit result entries to plot. Allowed values: “residual”, “contributions”, “restraints”, “chi2”, “reduced_chi2”. Default is None.

• plot_intermediate_result_names (list of str) – The list of intermediate result entries to plot during refinement. Allowed values: “residual”, “contributions”, “restraints”, “chi2”, “reduced_chi2”. Default is None.

Raises:

• FileNotFoundError – If the input data directory, output result directory, or structure file does not exist.

• NotADirectoryError – If input_data_dir or output_result_dir is not a directory.

• ValueError – If a refinable variable name is not found in the recipe, or if a plot result name is not valid.

Examples

>>> runner = SequentialCMIRunner()
>>> runner.load_inputs(
...     input_data_dir="./data",
...     structure_path="./structure.cif",
...     output_result_dir="./results",
...     refinable_variable_names=["a", "all"],
...     plot_variable_names=["a"],
...     plot_result_names=["chi2"],
...     plot_intermediate_result_names=["residual"],
... )

run(mode: Literal['batch', 'stream'])

Run the sequential refinement process in either batch or streaming mode.

Parameters:

mode (str) – The mode to run the sequential refinement. Must be either “batch” or “stream”. In “batch” mode, the toolset will run through all available input files once and then stop. In “stream” mode, the runner will continuously monitor the input data directory for new files and process them as they appear, until the user decides to stop the process.

set_start_input_file(input_filename, input_filename_to_result_filename)

Set the starting input file for sequential refinement and continue the interrupted sequential refinement from that point.

Parameters:

• input_filename (str) – The name of the input file to start from. This file must be in the input data directory.

• input_filename_to_result_filename (function) – The function that takes an input filename and returns the corresponding result filename. This is used to locate the last result file for loading variable values.