Menu

Instructions (part II: SubIval.dll functions)

The page contains a list of interface functions contained within the SubIval library (SubIval.dll). A more detailed explanation is available in the paper “Application of SubIval in solving initial value problems with fractional derivatives”,  Applied Mathematics and Computation 319, 86-103 (2018).

Some functions have been updated however and now have different names.

 

The Matlab/Octave and FreeMat (32-bit) examples are now available with a solver. The solver runs all the necessary functions, hence this is for researchers willing to modify the solvers.

 

Link initialization in a CAS

 

For MATLAB the initialization can be done with the line:

hS = actxserver('SubIval');

Then the hS object can be used to execute the functions (this should also work in older versions of MATLAB. Note that first the SubIval DLL needs to be registered e.g. by using the simple RegisterSubIval application that can be found under the SubIval archive  (it simply runs regasm.exe; the executable needs to be placed in the same folder as SubIval.dll).

For newer versions of MATLAB one can directly add the DLL:
NET.addAssembly('SubIval.dll');
hSubIval = SubIvalNS.SubIvalLauncher();

FreeMat (32-bit) only cooperates with C libraries, hence the SubIval C DLL. Each SubIval function needs to be registered separately, e.g. using the code:
import('SubIvalC.dll', 'establish', 'hSestablish', ...
'int32', '')
import('SubIvalC.dll', 'finish', 'hSfinish', ...
'void', '')
import('SubIvalC.dll', 'Initialize', 'hSInitialize', ...
'int32', 'int32 nProcesses')
import('SubIvalC.dll', 'InitializeProcess', 'hSInitializeProcess', ...
'int32', 'int32 iProc, int32 n_x, int32 pOrder, double t0, int32 type')
import('SubIvalC.dll', 'InitAlpha', 'hSInitAlpha', ...
'int32', 'int32 iProc, double Alpha_i, int32 i, int32 C0_RL1')
import('SubIvalC.dll', 'newt', 'hSnewt', ...
'int32', 'int32 iProc, double t_j')
import('SubIvalC.dll', 'correctt', 'hScorrectt', ...
'int32', 'int32 iProc, double t_j')
import('SubIvalC.dll', 'Putxi', 'hSPutxi', ...
'int32', 'int32 iProc, double x_i, int32 i')
import('SubIvalC.dll', 'ComputeInitial', 'hSComputeInitial', ...
'int32', 'int32 iProc')
import('SubIvalC.dll', 'ComputeStageA', 'hSComputeStageA', ...
'int32', 'int32 iProc')
import('SubIvalC.dll', 'ComputeStageB', 'hSComputeStageB', ...
'int32', 'int32 iProc')
import('SubIvalC.dll', 'geta', 'hSgeta', ...
'double', 'int32 iProc, int32 i')
import('SubIvalC.dll', 'getb', 'hSgetb', ...
'double', 'int32 iProc, int32 i')

import('SubIvalC.dll', 'getaMA', 'hSgetaMA', ...
'double', 'int32 iProc, int32 i')
import('SubIvalC.dll', 'getbMA', 'hSgetbMA', ...
'double', 'int32 iProc, int32 i')

Mathematica on the other hand supports the .NET Framework since its 5.0 version and can directly access the DLL. E.g. if it is placed in the same directory as the notebook – the following lines can be used to establish the link:

Needs["NETLink‘"];
InstallNET[];
ThePath=NoteBookDirectory[]<>"SubIval.dll";
SIAssembly = LoadNETAssembly[ThePath];
hS = NETNew["SubIval"];

 

Functions for SubIval setup

 

hS.Initialize(nProcesses);

can be used for the initialization of any number of SubIval processes. In most cases you will only need one SubIval process (i.e. nProcesses = 1). The above execution is for MATLAB. Mathematica simply uses the @ member access operator instead along with square brackets instead of parentheses.

hS.InitializeProcess(iProc, nx, pmov, t0, procType);

initializes the process with the zero based index iProc.nx determines the number of variables under fractional derivatives. pmov sets up the polynomial interpolation order in the internal computations (usually pmov = 4 is a good choice). t0 is the initial time instance (usually t0 = 0). procType is the process type – simple (procType = 0) or time step adaptive (2 stage) (procType = 1).
Next, the initial values for the variables under fractional derivatives need to be given along with the derivative orders. Assuming that a x0 and alphas arrays have been filled with the initial values and derivative orders respectively, one can use the following code:

for inx = 1:nx
errStr = hSubIval.InitAlpha(iProc, alphas(inx), inx-1, iC0RL1);
errStr = hSubIval.Putxi(iProc, x0(inx), inx-1);
end

iC0RL1 is the derivative definition, which SubIval should follow for the respective variable (iC0RL1 = 0 for the Caputo definition, iC0RL1 = 1 for the Riemann-Liouville fractional derivative).

 

Functions executed in a time step

 

At the start of a time step a new time instance tnew can be given with:

hSubIval.newt(iProc, tnew);

If a time step needs to be repeated (maximum error exceeded) one can use the following code for the correction of the time instance value:
hSubIval.correctt(iProc, tnew);

For a successful time step, after obtaining the vector of solutions xnew the following loop can be used to send them to the SubIval.dll:
for i1=1:nx
hS.Putxi(0, xnew(i1), i1-1);
end

Note that the library uses zero based indexing, in contrast to MATLAB and Mathematica where one based indexing is used.
For a simple process one only runs:
hS.ComputeSimple(iProc);

to compute the coefficients a and b for the fractional derivative approximation:

\( _{t_{0}}
\mathrm{D}
_{t}
^{\mathrm{\alpha}}
x(t)
\approx
ax(t)
+ b
.
\)

(1)

For a 2-stage process (for time step adaptivity) in the first time step one executes:
hS.ComputeInitial(iProc);

while in every next time step two a and b coefficient sets are obtained – first for stage A:
hS.ComputeStageA(iProc);

and then for the stage B:
hS.ComputeStageB(iProc);

Once the coefficients are obtained, for each variable one can obtain the a and b coefficients by using the following code:
for i1=1:nx
retObj = hS.getab(0,i1-1);
aa(i1)=retObj{2};
bb(i1)=retObj{3};
end

Where it is assumed that the arrays aa and bb have been created for the storage of the a and b coefficients respectively. In Mathematica the braces are replaced with double square brackets. Each of the interface functions (except getab) returns a string with an error message. If no exception has been thrown during the execution – the string contains the message "isOK". For getab it is placed as the first object in the returned array.