The MATLAB method (of the SIRENE or FLUVIA calculation program of SIC) starts the Matlab program at the initial time t=dt opening a DDE link and permits you to execute a .m Matlab file at each regulation time step dtu for this module (dtu can be a multiple of the numerical time step dt).

The Matlab .m script file will be used as detailed hereafter. The name of this file can be specified in the specific parameters of the method MATLAB (pidsic.m in the example provided in dat/exemple/matlab). It may indicate that name with either .m extension (ex .: pidsic.m) or without this extension (ex .: pidsic). In the case where the extension is not present it will be automatically added. If this file is found in the current sub-directory where the xml file of the current project is, then it will be the one used without offering the user to choose another one, which facilitates the user’s task. If this file does not exist in the current subdirectory, then a file can be selected from .m existing files in the data subdirectory. If no name is specified, then a default name is generated and sought: module2.m, module3.m, etc., or a generic module"n".m, where "n" is the controller number, starting usually at 2 (for the index 1 is used for the laws function of time, which are managed also internally as a regulator if necessary).

Be careful not to use a name for this .m file already used by an intrinsic Matlab function (example pid.m). With some versions of Matlab this does not pose any problem (ex 7.1) but with some other this will generate an error (ex Matlab 2010b).

In the interface when calculating steady flow scenarios (FLUVIA Program) or transient scenarios (SIREN Program), the names of these .m files from the project (xml file), automatically generated or selected by the user are shown.

At this initial time step (t=dt) the MATLAB method (of the SIRENE or FLUVIA calculation program of SIC) sends to the Matlab environment (workspace) : the calculation time step dt, the regulation time step dtu, the final time tfin and an "interf" flag allowing to manage the interfaces in the .m file according to the interface mode as defined in the option menu.

For this and every later time step t ≥ dt (multiple of dtu, see the discussion of dtu and dt), MATLAB method sends to the Matlab environment (workspace) controlled variables y, corresponding targets yt, measured variables z, current control variable positions u and current time t. The names of these variables can be redefined. These variables are vectors since they can be multiple. In Scilab the vectors are by defaut columns (size(u) = [nu 1]), contrary to Matlab where they are lines (size(u) = [1 nu]). These vectors y, yt and z are those of the current instant t. The vector u is that calculated at the current time t and which will be applied and effective from the moment of following calculation t + dt. If you want to have the history of these vectors it is for you to store them in variables in the Matlab memory space (the variables are stored and saved in memory between 2 calls), or possibly on a file.

The SIRENE (or FLUVIA) program then executes the selected Matlab .m file (at each time step t=n.dtu, n=1 to nmax such as t=nmax.dtu=tfin).

The SIRENE (or FLUVIA) program then retrieves the control action variables u from the Matlab workspace (as calculated by the .m file) and applies them into SIRENE (or FLUVIA).

This MATLAB regulation method permits you to write and test quickly a regulation method while taking advantage of all Matlab development environment. In addition, it does not require any compilation or link edition of the SIRENE (or FLUVIA) program. On the other hand, the regulation module execution is slower because of data exchanges between SIRENE (or FLUVIA) and Matlab, and because a .m file is interpreted by Matlab and not compiled directly in executable code. You can check this execution time since we provide the same example with the intrinsic PID regulation module, the Scilab and the MatLab DDE link and the wdlang module.

Example of .m file (see example provided under dat/ex4_matlab):

% file corresponding PIDSIC.M to a controller PID
% initialisation
% Matlab and Scilab manage vectors differently
% In Matlab, by default, a vector is a line (size (u) = 1 nu)
% In Scilab , a default vector is a column (size (u) = nu 1)
% To avoid unnecessary duplication of indexing, we adapt to that convention
% Matlab and Scilab scripts are then slightly different
 
if t == dt
   eold=0;
   se=0;
   de=0;
   [n1 nu]=size(u);
   vu=zeros(n1,nu)+1;
   [n1 ny]=size(y);
   vy=zeros(n1,ny)+1;
end;
 
% useful coefficient calculation
------
Kp=[14.78 1.44 4.22 2.51 1.53];
Ti=[1440 1680 1200 1440 1440];
Td=zeros(n1,nu);
N =zeros(n1,nu);
for i=1:nu,
   if Ti(i)==0;
      Ki(i)=0;
   else
      Ki(i)=Kp(i)/Ti(i)*dt/2;
   end
   if Td(i)==0;
      Kd1(i)=0;
      Kd2(i)=0;
   else
      if N==0
         Kd1(i)=0;
         Kd2(i)=Kp(i)*Td(i)/dt;
      else
         Kd1(i)=1/(1+N(i)/Td(i)*dt);
         Kd2(i)=Kp(i)*N(i)*Kd1(i);
      end;
   end;
end;
 
% calculation of the vectorial pid
------
e=yt-y;
se=se+Ki.*(eold+e);
de=Kd1.*de+Kd2.*(e-eold);
u=Kp.*e+se+de;
 
% old deviation saving 
------
eold=e;
 
% drawing of y and u
------
if interf == 1
   if t == dt
      subplot(211)
      xlabel('time (h)')
      ylabel('y, yt')
      axis([0 25 -.5 .5])
      title('Outputs, Targets');
      subplot(212)
      xlabel('time (h)')
      ylabel('u')
      axis([0 25 -1.5 1.5])
      title('Commands');
   end;
   subplot(211),plot(t*vy/3600,y,'g+',t*vy/3600,yt,'b+');
   subplot(212),plot(t*vu/3600,u,'r+');
end

The parameters for the MATLAB method are the name of the default .m file and the name of the variables in the Matlab workspace. These indications are optional because default names are provided.

In debug mode = 0 no syntax checking of the .m file is performed, in debug mode = 1 checks are performed and any messages are written to a matlab.dbg file (be careful to delete it at the end of the simulation because it is opened in "append" mode and the messages are concatenated at the end of the file if it already exists, it can therefore become very large), in debug mode = 2 the messages are, moreover, displayed on the screen. It is advisable to use mode 2 during debugging of the .m file and then to switch to mode 0 to do the routine simulations (time saving).

The location of the matlab.exe program can be specified, which is useful if different versions of Matlab are installed on the computer. But the desired version of Matlab must also be defined in the corresponding option in the "Options/Options" menu that manages the SIRENE and FLUVIA exe with the correct version of Matlab. The PATH system must also contain the reference to the Matlab subdirectory (of the correct version to be used), and that there is no reference before to another subdirectory also containing libraries like lapack.dll. Otherwise there will be a conflict (for example with another version of MatLab, or a version of Scilab, see below). In this case we can get an error message saying that Fluvia or Sirene does not find libmx.dll ("The program can not start because libmx.dll is missing from your computer"). The solutions can then be either to modify this path, or to temporarily rename the installation subdirectories of these other programs (you usually have administrator rights to do this).

You can also specify if you want to close or not Matlab at the end of the simulation (tick box selected to close Matlab).

The Matlab DDE link was compiled with Matlab version 6.5 (release 13) for versions 4.07 to 4.21, with version 7.1 (release 14) for version 4.22, and also with versions 7.4 (Release 2007a), 7.5 Release 2007b), 2008 and 2009. If you have another version, please contact us. With the libraries of your version we can normally compile a specific version adapted to your version of Matlab (currently only in 32 bits). Some versions of Matlab provide backwards compatibility with earlier versions of the Matlab DDE link, but Matlab’s policy on this point is unclear. Recent versions like the 2010b version of Matlab (Release 7.11.0.584 to be precise) is compatible with our versions of Fluvia and Sirene with the DDE MatLab 7.1 link. So even if your version of Matlab is not explicitly proposed in our list, we recommend that you test the different versions we offer with your version of Matlab before concluding that this is not available.

In the event of a problem when launching the DDE link (problem to launch Matlab, message that dlls are not found, or that procedure entry points are not found in dlls, or function not found) is that you probably have a conflict between various MatLab-related dll and Scilab installed on your computer. The problem is that these programs use a number of dlls, some of which have the same name, such as lapack.dll in particular. If you choose the option "No DDE link" (in the "Hydraulics" mode, go to the Options/Options menu, the "Select" button in the "Version of the DDE Matlab or Scilab" link), then the active FLUVIA and SIRENE programs are those that do not have DDE links with MatLab or Scilab. There will be no more conflict but you will not be able to use this DDE link. You will get a message in the display window during the calculation. You will have to choose the version of FLUVIA and SIRENE that corresponds to the version of MatLab or Scilab you use (installed on your computer) by choosing the "MatLab 6", "MatLab 7.1", "MatLab 7.4", "MatLab 7.5 "," MatLab 2008 "," MatLab 2009 "," Scilab 4 "or" Scilab 5 ". In this case, the corresponding FLUVIA and SIRENE exe, as well as the dlluser *.dll are copied to the SIC/EXE subdirectory and become the active versions.

If you have multiple versions of Matlab installed on your computer, you will need to define the one you want to use. To do this, follow the instructions on the Matlab forum (Register MATLAB as Automation Server):

https://fr.mathworks.com/help/matlab/matlab_external/register-matlab-as-automation-server.html?requestedDomain=nl.mathworks.com

Otherwise you might have a problem running Fluvia or Sirene when they attempt to open Matlab with the message "MATLAB can not be launched".