Custom Models in Python or C++#
RAT supports custom models written in MATLAB, Python or C++.
Between MATLAB and Python, the natural choice is to write a model in the same language as the the API you’re using. This will also likely be faster, since there is no computational overhead due to running a different language. Another common reason for making a particular choice of language is to take advantage of particular software libraries available in certain languages. The primary reason for C++ is for pure speed, where very computationally demanding custom models calculations are required.
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 SLDs
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 SLDs
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 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 SLDs
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.