itcsimlib.itc_model module

Basic itcsimlib model class.

class itcsimlib.itc_model.ITCModel(units='J', lattice_name=None, ligand_name=None)

Bases: object

A base class that serves as the foundation for generation of per-injection binding enthalpies

units

The units to report binding enthalpies in. Note that internally, all calculations should be performed in SI units (e.g. Joules)

Type:string

params

The parameters of the model

Type:ordered dict of strings

components

The names of the components that are involved in the binding model (e.g. the lattice/macromolecule and ligand)

Type:list of strings

lattice_name

The name of the binding component (for binary systems)

Type:string

ligand_name

The name of the bound component (for binary systems)

Type:string

Notes

Parameter types can be “n” (stoichiometry), “k” (a kinetic constant, not currently used), “dG” (change in free energy), “dH” (change in enthalpy), “dS” (change in entropy), or “dCp” (change in heat capacity) By convention, if lattice_name and ligand_name are not provided, they’ll be set to the first and second (respectively) components set by add_component()

add_parameter(name, type, bounds=[None, None], default=0.0, linked='', description='')

Register a model parameter.

Parameters:

• name (string) – The name of the model parameter. Should be descriptive, like “dG1” (e.g. the delta G(ibbs) energy for binding mode 1).
• type (string) – The type, i.e. energy, stoichiometry, etc. See class notes.
• bound (tuple) – The high and low boundaries for the parameter. Depending on the fitting mode, these may or not be enforced.
• default (float) – The default value for the parameter
• linked (string) – (Not used yet)
• description (string) – A description of the model parameter. Only ever reported to the user for their information.

Returns:

Return type:

None

add_component(name, description='')

Register a model component.

Parameters:

• name (string) – The name of the model component (e.g. “Lattice”, “Macromolecule”, or “Ligand”)
• description (string) – A description of the model component. Only ever reported to the user for their information.

Returns:

Return type:

None

start()

Class method stub for any necessary setup calls the model needs (scratch space, etc.). Actual models will need to overwrite this only if necessary.

Parameters:None – Returns: Return type:None

stop()

Class method stub for any necessary shutdown calls the model needs (clearing scratch space, etc.). Actual models will need to overwrite this only if necessary.

Parameters:None – Returns: Return type:None

set_units(units)

Set the units the model will A) receive parameter values, and B) return dQ heats.

Parameters:units (string) – The units to use for model parameters and dQ heats Returns: Return type:None

Notes

All internal calculations are still to be done in SI units (Joules)!

set_param(name, value)

Set the value of the single named parameter.

Parameters:

• name (string) – The name of the model parameter
• value (float) – The value to set the named model parameter too

Notes

If the model parameter is an energy, it will be automatically converted to Joules for storage from whatever units are currently specified

set_params(*args, **kwargs)

Set the values of multiple parameters.

Parameters:

• *args – Set the values of the model parameters in the order as returned by get_param_names().
• **kwargs – Set the values of the named model parameters.

Returns:

Return type:

None

Notes

To prevent confusion, when setting parameter values positionally, all model values must be specified (in the correct order of course).

get_params(units=None)

Return the value of all model parameters.

Parameters:units (string) – Use the specified units. If omitted, use the units already specified by the model (if applicable). Returns:Parameter name-keyed dict of values. Return type:OrderedDict

get_param(name, units=None)

Return the value of the specified model parameter.

Parameters:

• name (string) – The name of the parameter to return.
• units (string) – Use the specified units. If omitted, use the units already specified by the model (if applicable).

Returns:

The value of the parameter.

Return type:

float

get_param_names()

Return a list of the parameter names used by the model.

Parameters:None – Returns:The names of the model parameters. Return type:list of strings

get_component_names()

Return a list of the component names present in the model.

Parameters:None – Returns:The names of the model components. Return type:list of strings

get_param_type(name)

Return the type of the named model parameter.

Parameters:name (string) – Name of the model parameter. Returns:The type of the requested parameter (e.g. “n”, “k”, “dG”, “dH”, or “dCp”). See class notes. Return type:string

get_param_bounds(name)

Return the boundaries for the named model parameter.

Parameters:name (string) – Name of the model parameter. Returns:The high and low boundaries (if specified, otherwise they are None) for the requested model parameter. Return type:tuple of floats

get_param_description(name)

Return the description for the named model parameter.

Parameters:name (string) – Name of the model parameter. Returns:The description of the model parameter previously set by add_parameter(). Return type:string

Q(T0, T, concentrations)

Return the total binding heat at each injection predicted by the model and its current parameter values. This is just a stub, and child classes should implement their own calculations of Q.

Parameters:

• T0 (float) – The reference temperature to be used for the model (used in temperature-dependent dG, dH, dCp).
• T (float) – The temperature the titration was performed at.
• concentrations (list of dicts) – The concentration of components at each injection point.

Returns:

The total heat in the system at each injection point.

Return type:

list of floats