narumii.simpson

narumii.simpson

Simulator dataclass

Simulator(simpson_path, params=dict())

Simulator class to run SIMPSON simulations.

Parameters:

Name	Type	Description	Default
simpson_path	str	Path to the SIMPSON executable.	required

Attributes:

Name	Type	Description
simpson_path	str	Path to the SIMPSON executable.
angle_set	list	Euler angles as a list: [alpha1, beta1, gamma1, alpha2, beta2, gamma2].
params	dict	Experimental parameters for the simulation.
b	float	Dipolar coupling constant.

simulate

simulate(filenames=None, b=None, spin_rate=None, angle_set=None, **kwargs)

Run SIMPSON simulation with the given input file.

Parameters:

Name	Type	Description	Default
input_file		Path to the SIMPSON input file.	required

Returns:

Name	Type	Description
elapsed_time	float	Elapsed time for the simulation in seconds.

Optimizer dataclass

Optimizer(simpson_path, params=dict(), exp_type='CTDrenar')

Bases: Simulator

Optimizer class to optimize parameters in SIMPSON simulations.

Inherits from Simulator class and provides methods for parameter optimization. Currently optimizes the b (dipolar coupling) parameter.

optimize

optimize(param_name, residual_function=residual_function, bounds=(-1500, 0), method='bounded', options={'xatol': 1})

Optimize the specified parameter.

Parameters:

Name	Type	Description	Default
param_name	str	Name of the parameter to optimize (default: 'beff').	required
residual_function	Callable	Function to compute residuals.	residual_function
bounds	Sequence	(min, max) bounds for optimization.	(-1500, 0)
method	str	Optimization method supported in scipy.optimize.minimize_scalar (default: 'bounded').	'bounded'
options	dict	Additional options for the optimizer (default: {'xatol': 1}).	{'xatol': 1}

Returns:

Name	Type	Description
	optimization_result.x: float	Optimized parameter value.
	optimization_result.fun: float	Residual at optimized parameter.
elapsed_time	float	Elapsed time for the optimization in seconds.

simulate

simulate(filenames=None, b=None, spin_rate=None, angle_set=None, **kwargs)

Run SIMPSON simulation with the given input file.

Parameters:

Name	Type	Description	Default
input_file		Path to the SIMPSON input file.	required

Returns:

Name	Type	Description
elapsed_time	float	Elapsed time for the simulation in seconds.

create_filenames

create_filenames(basename, template=None, **kwargs)

Create filenames used for simulations based on a given basename.

Parameters:

Name	Type	Description	Default
basename	str	Base name for simulation files.	required
**kwargs	str	Additional filenames to include in the returned dictionary.	{}

Returns:

Name	Type	Description
filenames	dictionary	Container for filenames, with keys: 'template', 'input', 'output', 'log', etc..

create_input_file

create_input_file(filenames, params=None)

Create SIMPSON input file.

Parameters:

Name	Type	Description	Default
filenames	dict[str, str]	Container for filenames, must have keys: 'template', 'input', 'output'. template: the template file based on which the input file is created. input: the path of the created input file. output: the path of theoutput file to be created by simulation.	required
params	dict[str, str] | None	Container for simulation parameters.	None

Returns:

Type	Description
None

run_simulation

run_simulation(simpson_path, basename='./new_simulation', template=None, beff=None, params=[], verbose=True)

Run a single Simpson simulation using an input template and provided parameters.

Parameters:

Name	Type	Description	Default
simpson_path	str	Path to the Simpson executable.	required
basename	str	Basename of the simulation file. Files will be generated based on this basename: - input - basename.in - output - basename.fid Default is './new_simulation'.	'./new_simulation'
template	str	Path to the input template file used to generate the real input file from provided parameters. If None, the filename basename.template will be used. Default is None.	None
beff	float	Dipolar coupling constant in Hz. Should have the opposite sign to the product of the gyromagnetic ratios of both nuclei. Default is None.	None
params	list of str or dict	Simulation parameters. Can be either: - A list of strings in 'key=value' format, e.g., ['spin_rate=17000.0', 'l0=1'] - A dictionary of key-value pairs, e.g., {'spin_rate': '17000.0', 'l0': '1'} Default is None.	[]
verbose	bool	If True, print simulation progress to stdout. Default is True.	True

Returns:

Name	Type	Description
elapsed_time	float	Elapsed time for the simulation in seconds.

Examples:

>>> run_simulation(simpson_path, basename='sim', template='input_template.txt', beff=-600)
>>> run_simulation(simpson_path, basename='sim', template='input_template.txt', beff=-600, 
...                params=['spin_rate=17000.0', 'l0=1'])

run_optimization

run_optimization(simpson_path, exp_type, basename='./new_optimization', template=None, reference='./reference.txt', params=None, param_name='b', residual_function=compute_rmsd, method='bounded', bounds=(-1500, 0), options={'xatol': 1}, verbose=True)

Optimize a parameter using SIMPSON simulations. Runs by iteratively running simulations and comparing the results with a reference experimental data.

Parameters:

Name	Type	Description	Default
simpson_path	str	Path to the Simpson executable.	required
exp_type	str	Type of NMR experiment. Supported values (either in full capitalized or small forms): - 'CTDRENAR', 'CT-DRENAR' for CTDrenar experiments - 'REDOR', 'REAPDOR' for REDOR/REAPDOR experiments - 'REDOR3' for compensated REDOR experiments - 'DQ', 'DOUBLEQUANTUM', 'DOUBLE-QUANTUM' for double quantum spectroscopy	required
basename	str	Basename of the simulation file. Files will be generated based on this basename: - input - basename.in - output - basename.fid - log (as number-only csv) - basename.log - log (more readable with rich information) - basename.txt Default is './new_optimization'.	'./new_optimization'
template	str	Path to the input template file used to generate the real input file from provided parameters. If None, the filename basename.template will be used. Default is None.	None
reference	str	Path to the reference experimental data file. Default is './reference.txt'.	'./reference.txt'
params	list[str] or dict	Additional simulation parameters. Can be either: - A list of strings in 'key=value' format - A dictionary of key-value pairs Default is None.	None
param_name	str	Name of the parameter to be optimized. Default is 'b'.	'b'
residual_function	Callable	The function used to calculate the residual difference between simulation and experiment. Default is .functions.compute_rmsd.	compute_rmsd
method	str	Optimization method used by scipy.optimize. Currently only the method 'bounded' is implemented. See scipy document. Default is "bounded".	'bounded'
bounds	Sequence	Optimization bounds. Must have two finite items. See scipy document. Default is "bounded". (-1500, 0).	(-1500, 0)
options		A dictionary of additional solver options. See scipy document. Default is {'xatol': 1}.	{'xatol': 1}
verbose	bool	If True, print optimization progress to stdout. Default is True.	True

Returns:

Type	Description
tuple[float, float, float]	A tuple containing: - b_opt : float Optimized dipolar coupling constant value in Hz. - residual : float Residual (RMSD) at the optimized b_eff value. - elapsed_time : float Total elapsed time for optimization in seconds.

Examples:

>>> b_opt, residual, time = run_optimization(
...     simpson_path,
...     exp_type='CT-DRENAR',
...     basename='dataset_name_opt',
...     reference='dataset_name_int.txt', 
... )
>>> b_opt, residual, time = run_optimization(
...     simpson_path,
...     exp_type='CT-DRENAR',
...     basename='dataset_name_opt',
...     template='input_template.txt',
...     reference='dataset_name_int.txt', 
...     bounds=(-3000, 0), 
... )