1(ch_matlab)= 2 3# Using MATLAB with PETSc 4 5There are three basic ways to use MATLAB with PETSc: 6 71. {any}`sec_matlabdump` into files to be read into 8 MATLAB, 92. {any}`sec_matlabsocket` from 10 a running PETSc program to a MATLAB process where you may 11 interactively type MATLAB commands (or run scripts), and 123. {any}`sec_matlabengine` to send data back 13 and forth between PETSc and MATLAB where MATLAB commands are issued, 14 not interactively, but from a script or the PETSc program (this uses 15 the MATLAB Engine). 16 17For the latter two approaches one must `./configure` PETSc with the argument `--with-matlab [--with-matlab-dir=matlab_root_directory]`. 18 19(sec_matlabdump)= 20 21## Dumping Data for MATLAB 22 23### Dumping ASCII MATLAB data 24 25One can dump PETSc matrices and vectors to the screen in an ASCII format 26that MATLAB can read in directly. This is done with the command line 27options `-vec_view ::ascii_matlab` or `-mat_view ::ascii_matlab`. To 28write a file, use `-vec_view :filename.m:ascii_matlab` or 29`-mat_view :filename.m:ascii_matlab`. 30 31This causes the PETSc program to print the vectors and matrices every 32time `VecAssemblyEnd()` or `MatAssemblyEnd()` are called. To provide 33finer control over when and what vectors and matrices are dumped one can 34use the `VecView()` and `MatView()` functions with a viewer type of 35`PETSCVIEWERASCII` (see `PetscViewerASCIIOpen()`, `PETSC_VIEWER_STDOUT_WORLD`, 36`PETSC_VIEWER_STDOUT_SELF`, or `PETSC_VIEWER_STDOUT_(MPI_Comm)`). 37Before calling the viewer set the output type with, for example, 38 39``` 40PetscViewerPushFormat(PETSC_VIEWER_STDOUT_WORLD,PETSC_VIEWER_ASCII_MATLAB); 41VecView(A,PETSC_VIEWER_STDOUT_WORLD); 42PetscViewerPopFormat(PETSC_VIEWER_STDOUT_WORLD); 43``` 44 45The name of each PETSc variable printed for MATLAB may be set with 46 47``` 48PetscObjectSetName((PetscObject)A,"name"); 49``` 50 51If no name is specified, the object is given a default name using 52`PetscObjectName()`. 53 54### Dumping Binary Data for MATLAB 55 56One can also read PETSc binary files (see 57{any}`sec_viewers`) directly into MATLAB via the scripts available 58in `$PETSC_DIR/share/petsc/matlab`. This requires less disk space and is 59recommended for all but the smallest data sizes. One can also use 60 61``` 62PetscViewerPushFormat(viewer,PETSC_VIEWER_BINARY_MATLAB) 63``` 64 65to dump both a PETSc binary file and a corresponding `.info` file 66which `PetscReadBinaryMatlab.m` will use to format the binary file in 67more complex cases, such as using a `DMDA`. For an example, see 68<a href="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/dm/tutorials/ex7.c.html">DM Tutorial ex7</a>. 69In MATLAB one may then generate a useful structure. For 70example: 71 72```matlab 73setenv('PETSC_DIR','~/petsc'); 74setenv('PETSC_ARCH','arch-darwin-double-debug'); 75addpath('~/petsc/share/petsc/matlab'); 76gridData=PetscReadBinaryMatlab('output_file'); 77``` 78 79(sec_matlabsocket)= 80 81## Sending Data to an Interactive MATLAB Session 82 83One creates a viewer to MATLAB via 84 85``` 86PetscViewerSocketOpen(MPI_Comm,char *machine,int port,PetscViewer *v); 87``` 88 89(`port` is usually set to `PETSC_DEFAULT`; use `NULL` for the 90machine if the MATLAB interactive session is running on the same machine 91as the PETSc program) and then sends matrices or vectors via 92 93``` 94VecView(Vec A,v); 95MatView(Mat B,v); 96``` 97 98See {any}`sec_viewers` for more on PETSc viewers. One may 99start the MATLAB program manually or use the PETSc command 100`PetscStartMatlab(MPI_Comm,char *machine,char *script,FILE **fp)`; 101where `machine` and `script` may be `NULL`. It is also possible to 102start your PETSc program from MATLAB via `launch()`. 103 104To receive the objects in MATLAB, make sure that 105`$PETSC_DIR/$PETSC_ARCH/lib/petsc/matlab` and 106`$PETSC_DIR/share/petsc/matlab` are in the MATLAB path. Use 107`p = PetscOpenSocket();` (or `p = PetscOpenSocket(portnum)` if you 108provided a port number in your call to `PetscViewerSocketOpen()`), and 109then `a = PetscBinaryRead(p);` returns the object passed from PETSc. 110`PetscBinaryRead()` may be called any number of times. Each call 111should correspond on the PETSc side with viewing a single vector or 112matrix. `close()` closes the connection from MATLAB. On the PETSc 113side, one should destroy the viewer object with 114`PetscViewerDestroy()`. 115 116For an example, which includes sending data back to PETSc, see 117<a href="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/vec/vec/tutorials/ex42.c.html">Vec Tutorial ex42</a> 118and the associated `.m` file. 119 120(sec_matlabengine)= 121 122## Using the MATLAB Compute Engine 123 124One creates access to the MATLAB engine via 125 126``` 127PetscMatlabEngineCreate(MPI_Comm comm,char *machine,PetscMatlabEngine *e); 128``` 129 130where `machine` is the name of the machine hosting MATLAB (`NULL` 131may be used for localhost). One can send objects to MATLAB via 132 133``` 134PetscMatlabEnginePut(PetscMatlabEngine e,PetscObject obj); 135``` 136 137One can get objects via 138 139``` 140PetscMatlabEngineGet(PetscMatlabEngine e,PetscObject obj); 141``` 142 143Similarly, one can send arrays via 144 145``` 146PetscMatlabEnginePutArray(PetscMatlabEngine e,int m,int n,PetscScalar *array,char *name); 147``` 148 149and get them back via 150 151``` 152PetscMatlabEngineGetArray(PetscMatlabEngine e,int m,int n,PetscScalar *array,char *name); 153``` 154 155One cannot use MATLAB interactively in this mode but one can send MATLAB 156commands via 157 158``` 159PetscMatlabEngineEvaluate(PetscMatlabEngine,"format",...); 160``` 161 162where `format` has the usual `printf()` format. For example, 163 164``` 165PetscMatlabEngineEvaluate(PetscMatlabEngine,"x = \%g *y + z;",avalue); 166``` 167 168The name of each PETSc variable passed to MATLAB may be set with 169 170``` 171PetscObjectSetName((PetscObject)A,"name"); 172``` 173 174Text responses can be returned from MATLAB via 175 176``` 177PetscMatlabEngineGetOutput(PetscMatlabEngine,char **); 178``` 179 180or 181 182``` 183PetscMatlabEnginePrintOutput(PetscMatlabEngine,FILE*). 184``` 185 186There is a short-cut to starting the MATLAB engine with 187`PETSC_MATLAB_ENGINE_(MPI_Comm)`. 188 189If you are running PETSc on a cluster (or machine) that does not have a license for MATLAB, you might be able to run MATLAB on the 190`head node` of the cluster or some other machine accessible to the cluster using the `-matlab_engine_host hostname` option. 191 192## Licensing the MATLAB Compute Engine on a cluster 193 194To activate MATLAB on head node which does not have access to the internet. [^matlabsection-footnote] 195 196First ssh into the head node using the command: ssh node_name 197 198Obtain the Host Id using the command: ip addr | grep ether [^matlabsection-footnote2] 199You will see something like this: link/ether xx:xx:xx:xx:xx:xx ABC yy:yy:yy:yy:yy:yy 200Note the value: xx:xx:xx:xx:xx:xx 201 202Login to your MathWorks Account from a computer which has internet access. You will see the available license that your account has. Select a license from the list. 203 204:::{figure} /images/manual/mathworks-account.png 205::: 206 207Then, select Install and Activate option and select the Activate to Retrieve License File option. 208 209> :::{figure} /images/manual/mathworks-account-2.png 210> ::: 211 212Enter the information and click Continue. 213 214:::{figure} /images/manual/mathworks-account-3.png 215::: 216 217An option to download the License file will appear. Download it and copy the license file to the cluster (your home directory). 218Now, launch MATLAB where you have sshed into your head node. 219 220:::{figure} /images/manual/mathworks-account-4.png 221::: 222 223Select the Activate manually without the internet option and click Next >. 224Browse and locate the license file. 225 226:::{figure} /images/manual/mathworks-account-5.png 227::: 228 229MATLAB is activated and ready to use. 230 231```{rubric} Footnotes 232``` 233 234[^matlabsection-footnote]: <https://www.mathworks.com/matlabcentral/answers/259627-how-do-i-activate-matlab-or-other-mathworks-products-without-an-internet-connection> 235 236[^matlabsection-footnote2]: <http://www.mathworks.com/matlabcentral/answers/101892> 237
