dplus package

Submodules

dplus.Amplitudes module

class dplus.Amplitudes.Grid(q_max, grid_size)

Bases: object

This class is described in pages 12-15 of the paper

The class Grid is initialized with q_max and grid_size. It is used to create/describe a grid of q, theta, phi angle values. These values can be described using two sets of indexing:

1. The overall index m
2. The individual angle indices i, j, k

N

actual_size

angles_from_index(m)

Parameters:m – receives an overall index m Returns:returns the matching q, theta, and phi angle values

angles_from_indices(i, j, k)

receives angle indices i,j,k and returns their q, theta, and phi angle values.

Parameters:

• i – angle indice i
• j – angle indice j
• k – angle indice k

Returns:

q, theta, and phi angle values

create_grid()

a generator that returns q, theta, phi angles in phi-major order

index_from_angles(q, theta, phi)

receives angles q, theta, phi and returns the matching overall index m.

Parameters:

• q – q angle
• theta – theta angle
• phi – phi angle

Returns:

matching overall index m

index_from_indices(i, j, k)

receives angle indices i,j,k and returns the overall index m that matches them.

Parameters:

• i – angle indices i
• j – angle indices j
• k – angle indices k

Returns:

overall index m that matches the given i,j,k

indices_from_angles(q, theta, phi)

receives angles q, theta, phi, ands returns the matching indices i,j,k.

Parameters:

• q – q angle
• theta – theta angle
• phi – phi angle

Returns:

return indices i, j, k of given q, thta and phi

indices_from_index(m)

Parameters:m – receives an overall index m. Returns:individual q, theta, and phi indices: i, j, k

step_size

The difference between q’s in the grid.

Returns:double q_max/N

class dplus.Amplitudes.Amplitude(q_max, grid_size)

Bases: dplus.Amplitudes.Grid

The class Amplitude, by contrast, can be used to build an amplitude and then save that amplitude as an amplitude file, which can then be opened in D+ (or sent in a class AMP) but it itself cannot be added directly to the Domain parameter tree.

complex_amplitude_array

returns the values array as complex array.

Returns:complex array

create_grid(func)

Amplitude overrides grid’s create_grid method. Amplitude’s create_grid requires a function as an argument. This function must receive q, theta, phi and return two values, representing the real and imaginary parts of a complex number. The values returned can be a tuple, an array, or a python complex number (A+Bj). These values are then saved to the Ampltiude’s values property, and can also be accessed through the complex_amplitudes_array property as a numpy array of numpy complex types.

Parameters:func – a function that receives q, theta, phi and return two values, representing the real and imaginary parts of a complex number.

default_header

Return the default file headers values for amplidute class.

Returns:file headers of amplitude

description

headers

Returns the headers - default if amplitude was created nt python API or external if amplitude was created from a file. :return:

static load(filename)

A static method, load, which receives a filename of an Amplitude file, and returns an Amplitude instance with the values from that file already loaded.

Parameters:filename – filename of an Amplitude file Returns:instance of Amplitude class.

save(filename)

The function will save the information of the Amplitude class to an Amplitude file which can then be passed along to D+ to calculate its signal or perform fitting.

Parameters:filename – new amplitude file name

values

array that contains the grid intensity values as 2 values - real and imaginary

Returns:values array

dplus.CalculationInput module

class dplus.CalculationInput.CalculationInput(graph=None, x=None, y=None, use_gpu=True)

Bases: dplus.State.State

A base class of the parameters for dplus generate or fit.

args

build the arguments params for D+ backed from CalculationInput fields.

Returns:The json dict that is send to D+ backed

static copy_from_state(state)

creates a CalculationInput based on an existing state

Parameters:state – a State class instance Returns:new CalculationInput instance

static load_from_PDB(filename, qmax)

receives the location of a PDB file and qmax, and automatically creates a guess at the grid size based on the pdb.

Parameters:

• filename – location of a PDB file
• qmax – The max q value for the creation of the pdb grid size

Returns:

instance of GenerateInput

static load_from_state_file(filename)

receives the location of a file that contains a serialized parameter tree (state) and creates instance of / CalculationInput from the file.

Parameters:filename – location of a state file Returns:CalculationInput instance

load_graph(graph)

can receive an unordered graph, and create ordered x and y arrays

Parameters:graph – dictionary of x_key:y_val (can be unordered)

load_signal_file(signal_filename)

recieve signal filename and load the x vector and y vector from the signal file.

Parameters:signal_filename –

use_gpu

boolean flag, determines whether run the fit/generate calculation with or without gpu.

Returns:boolean value

x

x vector, float array of the qs values

Returns:array of floats

y

Returns:complex array of the intensity values for fitting

dplus.CalculationResult module

class dplus.CalculationResult.CalculationResult(calc_data, result, job)

Bases: object

Stores the various aspects of the result for further manipulation

error

Returns:returns the json error report from the dplus run

get_amp(model_ptr, destination_folder=None)

returns the file location of the amplitude file for given model_ptr. destination_folder has a default value of None, but if provided, the amplitude file will be copied to that location, and then have its address returned.

Parameters:

• model_ptr – int value of model_ptr
• destination_folder – location to copy the amplitude file of the given model_ptr

Returns:

File location of the amplitude file

get_amps(destination_folder=None)

fetches all the amplitude files created by the calculation, and returns an array of their folder locations. destination_folder has a default value of None, but if provided, the amplitude files will be copied to that folder

Parameters:destination_folder – optional location to save the amplitude files to Returns:Array of file locations of the amplitude files

get_pdb(model_ptr, destination_folder=None)

returns the file location of the pdb file for given model_ptr. destination_folder has a default value of None, but if provided, the pdb file will be copied to that location, and then have its address returned :param model_ptr: int value of model_ptr :param destination_folder: location to copy the pdb file of the given model_ptr :return: File location of the pdb file

graph

Returns:an OrderedDict whose keys are x values and whose values are y values.

headers

Returns:an OrderDict of headers, whose keys are ModelPtrs and whose values are the header associated.

save_to_out_file(filename)

receives file name, and saves the results to the file. :param filename: string of filename/path

y

Returns:The raw list of intensity values from the results json

class dplus.CalculationResult.FitResult(calc_data, result, job)

Bases: dplus.CalculationResult.CalculationResult

A class for fit calculation results

create_state_results()

This function creates CalculationInput class from the parameters tree returned from a Fit calculation :return:

parameter_tree

A json of parameters (can be used to create a new state with state’s load_from_dictionary). :return: A json of parameters

result_state

class dplus.CalculationResult.GenerateResult(calc_data, result, job)

Bases: dplus.CalculationResult.CalculationResult

A class for generate calculation results

dplus.CalculationRunner module

exception dplus.CalculationRunner.JobRunningException

Bases: Exception

class dplus.CalculationRunner.LocalRunner(exe_directory=None, session_directory=None)

Bases: dplus.CalculationRunner.Runner

The LocalRunner is intended for users who have the D+ executable files installed on their system. It takes two optional initialization arguments:

• exe_directory is the folder location of the D+ executables. By default, its value is None- on Windows, this will lead to the python interface searching the registry for an installed D+ on its own, but on linux the executable directory must be specified.
• session_directory is the folder where the arguments for the calculation are stored, as well as the output results, amplitude files, and pdb files, from the c++ executable. By default, its value is None, and an automatically generated temporary folder will be used.

class RunningJob(session_directory, pid=-1, calculation_type='generate')

Bases: dplus.CalculationRunner.RunningJob

implementation of RunningJob for localRunner class

abort()

The function abort ends the current localRunner job.

get_status()

The function get_status returns a json dictionary reporting the job’s current status.

Return type:a json dictionary.

fit(calc_data)

The method fit waits until dplus has returned a result.

Parameters:calc_data – an instance of a CalculationInput class Return type:an instance of a CalculationResult class

fit_async(calc_data)

The method fit_async allows dplus calculations to be run in the background.

Parameters:calc_data – an instance of a CalculationInput class Return type:an instance of a RunningJob class

generate(calc_data)

The method generate waits until dplus has returned a result.

Parameters:calc_data – an instance of a CalculationInput class Return type:an instance of a CalculationResult class

generate_async(calc_data)

The method generate_async allows dplus calculations to be run in the background.

Parameters:calc_data – an instance of a CalculationInput class Return type:an instance of a RunningJob class

static get_running_job(session)

session_directory

class dplus.CalculationRunner.Runner

Bases: object

abstract class that presents the interface for dplus calls.

fit(calc_data)

run sync dplus fit.

Parameters:calc_data – an instance of a CalculationInput class Return type:an instance of a FitResult class

fit_async(calc_data)

run async dplus fit.

Parameters:calc_data – an instance of a CalculationInput class Return type:an instance of a RunningJob class

generate(calc_data)

run sync dplus generate.

Parameters:calc_data – an instance of a CalculationInput class Return type:an instance of a GenerateResult class

generate_async(calc_data)

run async dplus generate.

Parameters:calc_data – an instance of a CalculationInput class Return type:an instance of a RunningJob class

class dplus.CalculationRunner.RunningJob(calculation_type)

Bases: object

abstract class for working with dplus jobs.

abort()

ends the current job.

get_result(calc_data)

The method get_results requires a copy of the CalculationInput used to create the job. / Should only be called when job is completed. It is the user’s responsibility to verify job completion with get_status before calling. :param calc_data: an instance of a CalculationInput class :rtype: an instance of a GenerateResult or FitResult class

get_status()

The function get_status returns a json dictionary reporting the job’s current status.

Return type:a json dictionary.

class dplus.CalculationRunner.WebRunner(base_url, token)

Bases: dplus.CalculationRunner.Runner

The WebRunner is intended for users accessing the D+ server. It takes two required initialization arguments, with no default values:

• url is the address of the server.
• token is the authentication token granting access to the server.

class RunningJob(base_url, token, session, calculation_type='generate')

Bases: dplus.CalculationRunner.RunningJob

implementation of RunningJob for WebRunner class

get_status()

The function get_status returns a json dictionary reporting the job’s current status.

Return type:a json dictionary.

fit(calc_data)

The method fit waits until dplus has returned a result.

Parameters:calc_data – an instance of a CalculationInput class Return type:an instance of a CalculationResult class

fit_async(calc_data)

The method fit_async allows dplus calculations to be run in the background.

Parameters:calc_data – an instance of a CalculationInput class Return type:an instance of a RunningJob class

generate(calc_data)

The method generate waits until dplus has returned a result.

Parameters:calc_data – an instance of a CalculationInput class Return type:an instance of a CalculationResult class

generate_async(calc_data)

The method generate_async allows dplus calculations to be run in the background.

Parameters:calc_data – an instance of a CalculationInput class Return type:an instance of a RunningJob class

static get_running_job(url, token, session)

dplus.CalculationRunner.as_job(job_dict)

this is the function used as an object hook for json deserialization of a dictionary to a job object. all changes made to __init__ of RunningJob need to be reflected here.

dplus.DataModels module

class dplus.DataModels.Constraints(max_val=inf, min_val=-inf, minindex=-1, maxindex=-1, link=-1)

Bases: object

The Constraints class contains the following properties:

• MaxValue: a float whose default value is infinity
• MinValue: a float whose default value is -infinity

static from_dictionary(json)

creates Constraints class instance with the json dictionary. :param json: json dictionary :return instance of Constraints class with the json data

serialize()

saves the contents of a class to a dictionary.

Returns:dictionary of the class fields (isConstrained, consMin and consMax)

class dplus.DataModels.Parameter(value=0, sigma=0, mutable=False, constraints=<dplus.DataModels.Constraints object>)

Bases: object

The Parameter class contains the following properties:

• value: a float whose default value is 0
• sigma: a float whose default value is 0
• mutable: a boolean whose default value is False
• constraints: an instance of the Constraints class, by default it is the default Constraints

isConstrained

check if there are constrains. Return True is there is at least on constrain value.

Returns:True

serialize()

saves the contents of a class to a dictionary. unlike other serialize methods, not used in creating ParamterTree to send to D+ Calculation. Serialized parameters are expected by D+ as a result of fitting.

Returns:dictionary of the class fields (Value, isMutable, consMinIndex,consMaxIndex, linkIndex, sigma and constraints)

class dplus.DataModels.Model

Bases: object

A base class to D+ models.

get_mutable_params()

used in combining fitting results, or running fitting from within python

Returns:returns all the mutables params in extra_params and location_params

load_from_dictionary(json)

sets the values of the various fields within a class to match those contained within a suitable dictionary.

Parameters:json – json dictionary

serialize()

saves the contents of a class to a dictionary.

Returns:dictionary of the class fields.

set_mutable_params(mut_arr)

receives an order array of mutable params and set the values in extra_params and location_params according to that array

Parameters:mut_arr – array of mutable params

class dplus.DataModels.ModelWithChildren

Bases: dplus.DataModels.Model

D+ has few models which can have children. For example: Domain, population and Symmetry models

load_from_dictionary(json)

sets the values of the various fields within a class to match those contained within a suitable dictionary.

Parameters:json – json dictionary

serialize()

saves the contents of a class to a dictionary.

Returns:dictionary of the class fields.

class dplus.DataModels.ModelWithLayers

Bases: dplus.DataModels.Model

D+ has few models which can have layers. For example: Sphere, Helix and UniformHollowCylinder

get_mutable_params()

Return all the mutable params of the model. The mutable params come from the layers array, extra_params and location_params.

Returns:mutable params array

load_from_dictionary(json)

sets the values of the various fields within a class to match those contained within a suitable dictionary.

Parameters:json – json dictionary

parameters_to_json_arrays()

serialize()

saves the contents of a class to a dictionary.

Returns:dictionary of the class fields.

set_mutable_params(mut_array)

receives an order array of mutable params and set the values in layer , extra_params and location_params according to that array.

Parameters:mut_arr – array of mutable params

class dplus.DataModels.ModelWithFile(filename='')

Bases: dplus.DataModels.Model

D+ has few models which have a file. For example: PDB, AMP and ScriptedSymmetry

load_from_dictionary(json)

sets the values of the various fields within a class to match those contained within a suitable dictionary.

Parameters:json – json dictionary

serialize()

saves the contents of a class to a dictionary.

Returns:dictionary of the class fields.

class dplus.DataModels.ScriptedSymmetry(**fields)

Bases: dplus.DataModels.Model

A class for D+ ScriptedSymmetry, this is sufficient for running against existing backend, but does NOT implement running with python fit

load_from_dictionary(json)

sets the values of the various fields within a class to match those contained within a suitable dictionary.

Parameters:json – json dictionary

serialize()

saves the contents of a class to a dictionary.

Returns:dictionary of the class fields.

class dplus.DataModels.Population

Bases: dplus.DataModels.ModelWithChildren

Population can contain a number of Model classes. Some models have children, which are also models.

add_model(model)

Parameters:model – model to add to the population

index = -1

load_from_dictionary(json)

sets the values of the various fields within a class to match those contained within a suitable dictionary.

Parameters:json – json dictionary

models

Return all the models in the population class.

Returns:models array

serialize()

saves the contents of a class Population to a dictionary.

Returns:dictionary of the class fields.

class dplus.DataModels.Domain

Bases: dplus.DataModels.ModelWithChildren

The Domain class describes the parameter tree. The Domain model is the root of the parameter tree, which can contain multiple populations.

index = -1

load_from_dictionary(json)

sets the values of the various fields within a class to match those contained within a suitable dictionary.

Parameters:json – json dictionary

populations

Returns:The populations of the domain

serialize()

saves the contents of a class Domain to a dictionary.

Returns:dictionary of the class fields.

dplus.FileReaders module

class dplus.FileReaders.SignalFileReader(filename)

Bases: object

SignalFileReader class can be initialized with a path to a signal file (eg a .out or .dat file) and will read that file into its x_vec, y_vec, and graph properties.

dplus.State module

class dplus.State.DomainPreferences

Bases: object

The DomainPreferences class contains properties that are copied from the D+ interface. Their usage is explained in the D+ documentation.

convergence

convergence: A convergence criteria for the orientation average. Usually

10e-3 or so. See manual, chapter 6.

generated_points

The number of point to generate between qmin to qmax

default value is 800

grid_size

The size of the the grid to be used (or not if !UseGrid). Must be a positive even integer. Minimum size is 20.

load_from_dictionary(json)

sets the values of the various fields within a class to match those contained within a suitable dictionary.

Parameters:json – json dictionary

orientation_iterations

The number of iterations (or depth in the case of Gauss

Krondrod) to be used in the orientation average. A good default value is 1,000,000. See manual, chapter 6.

orientation_method

[“Monte Carlo (Mersenne Twister)”,”Adaptive (VEGAS) Monte Carlo”,”Adaptive Gauss Kronrod”] See manual chapter 6. The first is the only one implemented on both CPU and GPU. Selecting VEGAS makes the amplitudes not be saved to files (they never leave the GPU), but is often much faster then vanilla Monte Carlo.

q_max

The maximal value in the q range. If SignalFile is not blank, qMax must equal the largest x-value in the SignalFile

q_min

The maximal value in the q range. If SignalFile is not blank, qMax must equal the largest x-value in the SignalFile

serialize()

signal_file

The path to the signal file. Must be present when fitting,

optional when generating (Generate uses the x-values from this file)

use_grid

boolean flag for using or not using grid

class dplus.State.FittingPreferences

Bases: object

convergence

# The convergence criteria passed on to Ceres that determines # when the fitting process has converged. # Required.

der_eps

# Parameter for ceres. Not entirely sure how this is used,

# beyond that it’s used for computing derivatives.

dogleg_type

valid values: # [“Traditional Dogleg”,”Subspace Dogleg”]

fitting_iterations

# The number of iterations the fitter should use before stopping.

# Note that this is also the number of “inner iterations” that # ceres uses (http://ceres-solver.org/nnls_solving.html#inner-iterations).

line_search_direction_type

# [“Steepest Descent”,”Nonlinear Conjugate Gradient”,”L-BFGS”,”BFGS”] # If “Nonlinear Conjugate Gradient”, NonlinearConjugateGradientType # must be valid.

line_search_type

load_from_dictionary(json)

loss_func_param_one

required for all loss functions but Trivial

loss_func_param_two

required for Tolerant Loss function

loss_function

See http://ceres-solver.org/nnls_tutorial.html for explanation. acceptable values: “Trivial Loss”,”Huber Loss”,”Soft L One Loss”,”Cauchy Loss”,”Arctan Loss”,”Tolerant Loss”

minimizer_type

Required. Valid values: [“Line Search”,”Trust Region”]

# If “Trust Region”, TrustRegionStrategyType must be valid. # If “Line Search”, lineSearchType must be valid.

nonlinear_conjugate_gradient_type

# [“Fletcher Reeves”,”Polak Ribirere”,”Hestenes Stiefel”] # See ceres documentation.

serialize()

step_size

# Parameter for ceres. Not entirely sure how this is used,

# beyond that it’s used for computing derivatives.

trust_region_strategy_type

# [“Levenberg-Marquardt”,”Dogleg”] # If “Dogleg”, then DoglegType must be valid.

validate()

x_ray_residuals_type

# [“Normal Residuals”,”Ratio Residuals”,”Log Residuals”]

# A function that determines how the residuals are treated. # Apparently not documented anywhere. Corresponds to [XRayResiduals, # XRayRatioResiduals,XRayLogResiduals] in modelfitting.cpp. # Required.

class dplus.State.State

Bases: object

The state class contains an instance of each of three classes: DomainPreferences, FittingPreferences, and Domain.

add_amplitude(amplitude, population_index=0)

is a convenience function specifically for adding instances of the Amplitude class. It creates an instance of AMP with the Amplitude’s filename, and then in addition to calling add_model with that AMP, it also changes the state’s DomainPreferences (specifically grid_size, q_max, and use_grid) to match the Amplitude’s properties. It returns the AMP it created.

Parameters:

• amplitude – instance of Amplitude
• population_index – int value that indicate where to add the new model that was created from the amplitude

Returns:

AMP type model

add_model(model, population_index=0)

is a convenience function to help add models to the state’s parameter tree. It receives the model and optionally a population index (default 0), and will insert that model into the population.

Parameters:

• model – instance of ‘Model’ type
• population_index – int value

export_all_parameters(filename)

call the function serialize and save the result (dictionary of the class fields) to a given filename

Parameters:filename – filename as string

get_model(name_or_ptr)

return a model from the Domain field by either its name or its model_ptr.

Return type:an instance of Model

get_models_by_type(type)

returns a list of Models from the Domain field with a given type_name.

Parameters:type – a string of model type , e.g. UniformHollowCylinder. Return type:list of instances of ‘Model’

get_mutable_parameter_values()

returns the values of all the mutable parameters in the Domain field.

Return type:a list of floats

get_mutable_params()

return array of arrays of all mutable parameters in tree.

Return type:a list of Parameters

load_from_dictionary(json)

sets the values of the various fields within a class to match those contained within a suitable dictionary. It can behave recursively as necessary, for example with a model that has children.

Parameters:json – json dictionary

serialize()

saves the contents of a class to a dictionary.

Returns:dictionary of the class fields (DomainPreferences, FittingPreferences and Domain)

set_mutable_parameter_values(param_vals_array)

sets the mutable parameters values in the Domain field with the the input list (in the order given by get_mutable_parameter_values).

Parameters:param_vals_array – a list of floats