Custom Models in Python or C++#
Custom models are usually written in MATLAB, but RAT allows alternative languages to be used. You can write your custom models either in Python or C++. The reason for the Python functionality is mainly since this is the more natural choice when using RAT from Python with pythonRAT, but also because the user might choose to incorporate Python libraries into the custom models that are not available in MATLAB. The reason for C++ if for pure speed, where very computationally demanding custom models calculations are required. Both options are easy to use in RAT.
Note
Examples of using Python and C++ custom models can be found in the /examples/miscellaneous/alternativeLanguages folder
Python Custom Models#
Note
Before you use Python from your MATLAB session, please ensure that Python is configured correctly on your system.
Custom models in Python and MATLAB are very similar in structure as shown below:
% customBilayer.m
function [output,sub_rough] = customBilayer(params,bulk_in,bulk_out,contrast)
sub_rough = params(1);
oxide_thick = params(2);
oxide_hydration = params(3);
lipidAPM = params(4);
headHydration = params(5);
bilayerHydration = params(6);
bilayerRough = params(7);
waterThick = params(8);
% We have a constant SLD for the oxide..
oxide_SLD = 3.41e-6;
% Now make the lipid layers..
% Use known lipid volume and compositions
% to make the layers
% define all the neutron b's.
bc = 0.6646e-4; %Carbon
bo = 0.5843e-4; %Oxygen
bh = -0.3739e-4; %Hydrogen
bp = 0.513e-4; %Phosphorus
bn = 0.936e-4; %Nitrogen
bd = 0.6671e-4; %Deuterium
% Now make the lipid groups..
COO = (4*bo) + (2*bc);
GLYC = (3*bc) + (5*bh);
CH3 = (2*bc) + (6*bh);
PO4 = (1*bp) + (4*bo);
CH2 = (1*bc) + (2*bh);
CHOL = (5*bc) + (12*bh) + (1*bn);
% Group these into heads and tails:
Head = CHOL + PO4 + GLYC + COO;
Tails = (34*CH2) + (2*CH3);
% We need volumes for each.
% Use literature values:
vHead = 319;
vTail = 782;
% we use the volumes to calculate the SLD's
SLDhead = Head / vHead;
SLDtail = Tails / vTail;
% We calculate the layer thickness' from
% the volumes and the APM...
headThick = vHead / lipidAPM;
tailThick = vTail / lipidAPM;
% Manually deal with hydration for layers in
% this example.
oxSLD = (oxide_hydration * bulk_out(contrast)) + ((1 - oxide_hydration) * oxide_SLD);
headSLD = (headHydration * bulk_out(contrast)) + ((1 - headHydration) * SLDhead);
tailSLD = (bilayerHydration * bulk_out(contrast)) + ((1 - bilayerHydration) * SLDtail);
% Make the layers
oxide = [oxide_thick oxSLD sub_rough];
water = [waterThick bulk_out(contrast) bilayerRough];
head = [headThick headSLD bilayerRough];
tail = [tailThick tailSLD bilayerRough];
output = [oxide ; water ; head ; tail ; tail ; head];
end
# customBilayer.py
import numpy as np
def customBilayer(params, bulk_in, bulk_out, contrast):
params = np.array(params)
bulk_in = np.array(bulk_in)
bulk_out = np.array(bulk_out)
sub_rough = params[0]
oxide_thick = params[1]
oxide_hydration = params[2]
lipidAPM = params[3]
headHydration = params[4]
bilayerHydration = params[5]
bilayerRough = params[6]
waterThick = params[7]
# We have a constant SLD for the oxide..
oxide_SLD = 3.41e-6
# Now make the lipid layers..
# Use known lipid volume and compositions
# to make the layers
# define all the neutron b's.
bc = 0.6646e-4 # Carbon
bo = 0.5843e-4 # Oxygen
bh = -0.3739e-4 # Hydrogen
bp = 0.513e-4 # Phosphorus
bn = 0.936e-4 # Nitrogen
bd = 0.6671e-4 # Deuterium
# Now make the lipid groups..
COO = (4*bo) + (2*bc)
GLYC = (3*bc) + (5*bh)
CH3 = (2*bc) + (6*bh)
PO4 = (1*bp) + (4*bo)
CH2 = (1*bc) + (2*bh)
CHOL = (5*bc) + (12*bh) + (1*bn)
# Group these into heads and tails:
Head = CHOL + PO4 + GLYC + COO
Tails = (34*CH2) + (2*CH3)
# We need volumes for each.
# Use literature values:
vHead = 319
vTail = 782
# we use the volumes to calculate the SLD's
SLDhead = Head / vHead
SLDtail = Tails / vTail
# We calculate the layer thickness' from
# the volumes and the APM...
headThick = vHead / lipidAPM
tailThick = vTail / lipidAPM
# Manually deal with hydration for layers in
# this example.
oxSLD = (oxide_hydration * bulk_out[contrast]) + ((1 - oxide_hydration) * oxide_SLD)
headSLD = (headHydration * bulk_out[contrast]) + ((1 - headHydration) * SLDhead)
tailSLD = (bilayerHydration * bulk_out[contrast]) + ((1 - bilayerHydration) * SLDtail)
# Make the layers
oxide = [oxide_thick, oxSLD, sub_rough]
water = [waterThick, bulk_out[contrast], bilayerRough]
head = [headThick, headSLD, bilayerRough]
tail = [tailThick, tailSLD, bilayerRough]
output = np.array([oxide, water, head, tail, tail, head])
return output, sub_rough
To use a python custom model from RAT, you need to add it to the current project, taking care to specify the language correctly.
problem.addCustomFile('myModel', 'customBilayer.py', 'python', pwd);
problem.custom_files.append(name='myModel', filename='customBilayer.py', language='python')
You can then use this in your calculations in the same way as a normal, MATLAB custom model.
C++ Custom Models#
If MATLAB or Python custom models are too slow, you also have the option of providing a C++ custom model. You then have to compile and build this into a shared library in order to use it with RAT.
Following on from our custom bilayer examples, the equivalent C++ custom model should follow this format.
//customBilayer.cpp
#include <vector>
#if defined(_WIN32) || defined(_WIN64)
#define LIB_EXPORT __declspec(dllexport)
#else
#define LIB_EXPORT
#endif
// We user extern "C" decorator to avoid name mangling....
extern "C" {
LIB_EXPORT void customBilayer(std::vector<double>& params, std::vector<double>& bulkIn, std::vector<double>& bulkOut, int contrast, std::vector<double>& output, double* outputSize, double* rough)
{
double subRough = params[0];
double oxideThick = params[1];
double oxideHydration = params[2];
double lipidAPM = params[3];
double headHydration = params[4];
double bilayerHydration = params[5];
double bilayerRough = params[6];
double waterThick = params[7];
// We have a constant SLD for the oxide
double oxideSLD = 3.41e-6;
// Now make the lipid layers..
// Use known lipid volume and compositions
// to make the layers
// define all the neutron b's.
double bc = 0.6646e-4; //Carbon
double bo = 0.5843e-4; //Oxygen
double bh = -0.3739e-4; //Hydrogen
double bp = 0.513e-4; //Phosphorus
double bn = 0.936e-4; //Nitrogen
double bd = 0.6671e-4; //Deuterium
// Now make the lipid groups..
double COO = (4*bo) + (2*bc);
double GLYC = (3*bc) + (5*bh);
double CH3 = (2*bc) + (6*bh);
double PO4 = (1*bp) + (4*bo);
double CH2 = (1*bc) + (2*bh);
double CHOL = (5*bc) + (12*bh) + (1*bn);
// Group these into heads and tails:
double Head = CHOL + PO4 + GLYC + COO;
double Tails = (34*CH2) + (2*CH3);
// We need volumes for each.
// Use literature values:
double vHead = 319;
double vTail = 782;
// we use the volumes to calculate the SLD's
double SLDhead = Head / vHead;
double SLDtail = Tails / vTail;
// We calculate the layer thickness' from
// the volumes and the APM...
double headThick = vHead / lipidAPM;
double tailThick = vTail / lipidAPM;
// Manually deal with hydration for layers in
// this example.
double oxSLD = (oxideHydration * bulkOut[contrast]) + ((1 - oxideHydration) * oxideSLD);
double headSLD = (headHydration * bulkOut[contrast]) + ((1 - headHydration) * SLDhead);
double tailSLD = (bilayerHydration * bulkOut[contrast]) + ((1 - bilayerHydration) * SLDtail);
// Make the layers
// oxide...
output.push_back(oxideThick);
output.push_back(oxSLD);
output.push_back(subRough);
// Water...
output.push_back(waterThick);
output.push_back(bulkOut[contrast]);
output.push_back(bilayerRough);
// Heads...
output.push_back(headThick);
output.push_back(headSLD);
output.push_back(bilayerRough);
// Tails...
output.push_back(tailThick);
output.push_back(tailSLD);
output.push_back(bilayerRough);
// Tails...
output.push_back(tailThick);
output.push_back(tailSLD);
output.push_back(bilayerRough);
// Heads...
output.push_back(headThick);
output.push_back(headSLD);
output.push_back(bilayerRough);
*rough = subRough;
outputSize[0] = 6; // row - Necessary to output how many layers in stack
outputSize[1] = 3;
}
} // extern "C"
Before you can use this file, you need to compile and build it into a shared library. The details will vary according to you system, for example
Clang on Apple (OSX)
clang -c customBilayer.cpp -o customBilayer.o -std=c++11 -arch x86_64 clang -shared customBilayer.o -o customBilayer.dylib -arch x86_64 -lc++
GCC on Linux:
g++ -fPIC -c customBilayer.cpp -o customBilayer.o -std=c++11 g++ -shared customBilayer.o -o customBilayer.so
Windows (with MSVC):
cl /EHsc /LD customBilayer.cpp
This will create either customBilayer.dylib (OSX), customBilayer.dll (Windows) or customBilayer.so (Linux).
To use this, we just add the relevant model to out project, in the same way as for MATLAB and Python models:
problem.addCustomFile('DSPC Model', 'customBilayer.dylib', 'cpp', pwd);
problem.custom_files.append(name='DSPC Model', filename='customBilayer.dylib', language='cpp')
You can then use your C++ custom model in your project as normal.