annotate pldoc/plml.tex @ 37:89688ebc447f tip

Deprecating this repository.

\documentclass[10pt]{article}
\usepackage{pldoc}
\sloppy
\makeindex

\begin{document}
% This LaTeX document was generated using the LaTeX backend of PlDoc,
% The SWI-Prolog documentation system



\section{plml: Prolog-Matlab interface}

\label{sec:plml}

\begin{tags}
    \tag{To be done}
Use mat(I) and tmp(I) as types to include engine Id.

Clarify relationship between return values and valid Matlab denotation.

Reshape/2 array representation: reshape([ ... ],Size)
Expression language: arr(Vals,Shape,InnerFunctor) - allows efficient
representation of arrays of arbitrary things. Will require more strict
nested list form.

Deprecate old array(Vals::Type) and cell(Vals::Type) left-value syntax.

Remove I from \dcgref{ml_expr}{2} and add to mx type?
\end{tags}

\paragraph{Types}

\textbf{ml_eng} - Any atom identifying a Matlab engine.

\textbf{ml_stmt} - A Matlab statement

\begin{code}
X;Y     :: ml_stmt :-  X:ml_stmt, Y:ml_stmt.
X,Y     :: ml_stmt :-  X:ml_stmt, Y:ml_stmt.
X=Y     :: ml_stmt :-  X:ml_lval, Y:ml_expr.
hide(X) :: ml_stmt :-  X:ml_stmt.
\end{code}

\begin{code}
ml_expr(A)       % A Matlab expression, possibly with multiple return values
ml_loc ---> mat(atom,atom).  % Matbase locator
\end{code}

\paragraph{Matlab expression syntax}

The Matlab expression syntax adopted by this module allows Prolog terms to represent
or denote Matlab expressions. Let T be the domain of recognised Prolog terms (corresponding to
the type ml_expr), and M be the domain of Matlab expressions written in Matlab syntax.
Then V : T\Sifthen{}M is the valuation function which maps Prolog term X to Matlab expression V[X].
These are some of the constructs it recognises:

Constructs valid only in top level statements, not subexpressions:

\begin{code}
X;Y             % |--> V[X]; V[Y]  (sequential evaluation hiding first result)
X,Y             % |--> V[X], V[Y]  (sequential evaluation displaying first result)
X=Y             % |--> V[X]=V[Y] (assignment, X must denote a valid left-value)
hide(X)         % |--> V[X]; (execute X but hide return value)
\end{code}

Things that look and work like Matlab syntax (more or less):

\begin{code}
+X              % |--> uplus(V[X])
-X              % |--> uminus(V[X])
X+Y             % |--> plus(V[X],V[Y])
X-Y             % |--> minus(V[X],V[Y])
X^Y             % |--> mpower(V[X],V[Y])
X*Y             % |--> mtimes(V[X],V[Y])
X/Y             % |--> mrdivide(V[X],V[Y])
X\Y             % |--> mldivide(V[X],V[Y])
X.^Y            % |--> power(V[X],V[Y])
X.*Y            % |--> times(V[X],V[Y])
X./Y            % |--> rdivide(V[X],V[Y])
X.\Y            % |--> ldivide(V[X],V[Y])
X:Y:Z           % |--> colon(V[X],V[Y],V[Z])
X:Z             % |--> colon(V[X],V[Z])
X>Z             % |--> gt(V[X],V[Y])
X>=Z            % |--> ge(V[X],V[Y])
X<Z             % |--> lt(V[X],V[Y])
X=<Z            % |--> le(V[X],V[Y])
X==Z            % |--> eq(V[X],V[Y])
[X1,X2,...]     % |--> [ V[X1], V[X2], ... ]
[X1;X2;...]     % |--> [ V[X1]; V[X2]; ... ]
{X1,X2,...}     % |--> { V[X1], V[X2], ... }
{X1;X2;...}     % |--> { V[X1]; V[X2]; ... }
@X              % |--> @V[X] (function handle)
\end{code}

Things that do not look like Matlab syntax but provide standard Matlab features:

\begin{code}
'Infinity'      % |--> inf (positive infinity)
'Nan'           % |--> nan (not a number)
X``             % |--> ctranpose(V[X]) (conjugate transpose, V[X]')
X#Y             % |--> getfield(V[X],V[q(Y)])
X\\Y            % |--> @(V[X])V[Y] (same as lambda(X,Y))
\\Y             % |--> @()V[Y] (same as thunk(Y))
lambda(X,Y)     % |--> @(V[X])V[Y] (anonymous function with arguments X)
thunk(Y)        % |--> @()V[Y] (anonymous function with no arguments)
vector(X)       % |--> horzcat(V[X1],V[X2], ...)
atvector(X)     % as vector but assumes elements of X are assumed all atomic
cell(X)         % construct 1xN cell array from elements of X
`X              % same as q(X)
q(X)            % wrap V[X] in single quotes (escaping internal quotes)
qq(X)           % wrap V[X] in double quotes (escaping internal double quotes)
tq(X)           % wrap TeX expression in single quotes (escape internal quotes)
\end{code}

Referencing different value representations.

\begin{code}
mat(X,Y)           % denotes a value in the Matbase using a dbload expression
mx(X:mx_blob)      % denotes an MX Matlab array in SWI memory
ws(X:ws_blob)      % denotes a variable in a Matlab workspace
wsseq(X:ws_blob)   % workspace variable containing list as cell array.
\end{code}

Tricky bits.

\begin{code}
apply(X,AX)        % X must denote a function or array, applied to list of arguments AX.
cref(X,Y)          % cell dereference, |--> V[X]{ V[Y1], V[Y2], ... }
arr(Lists)         % multidimensional array from nested lists.
arr(Lists,Dims)    % multidimensional array from nested lists.
\end{code}

Things to bypass default formatting

\begin{code}
noeval(_)          % triggers a failure when processed
atom(X)            % write atom X as write/1
term(X)            % write term X as write/1
\(P)               % escape and call phrase P directly to generate Matlab string
$(X)               % calls pl2ml_hook/2, denotes V[Y] where plml_hook(X,Y).
'$VAR'(N)          % gets formatted as p_N where N is assumed to be atomic.
\end{code}

All other Prolog atoms are written using \predref{write}{1}, while other Prolog terms
are assumed to be calls to Matlab functions named according to the head functor.
Thus V[ $<$head$>$( $<$arg1$>$, $<$arg2$>$, ...) ] = $<$head$>$(V[$<$arg1$>$, V[$<$arg2$>$], ...).

There are some incompatibilities between Matlab syntax and Prolog syntax,
that is, syntactic structures that Prolog cannot parse correctly:

\begin{itemize}
    \item 'Command line' syntax, ie where a function of string arguments:
"save('x','Y')" can be written as "save x Y" in Matlab,
but in Prolog, you must use function call syntax with quoted arguments:
save(`x,`'Y').
    \item Matlab's postfix transpose operator "x'" must be written using a different
posfix operator "x``" or function call syntax "ctranspose(x)".
    \item Matlab cell referencing using braces, as in x\{1,2\} must be written
as "cref(x,1,2)".
    \item Field referencing using dot (.), eg x.thing - currently resolved
by using hash (\#) operator, eg x\#thing.
    \item Using variables as arrays and indexing them. The problem is that
Prolog doesn't let you write a term with a variable as the head
functor.
\end{itemize}

\vspace{0.7cm}

\begin{description}
    \predicate[nondet,multifile]{matlab_init}{2}{-Key, -Cmd:ml_expr}
Each user-defined clause of \predref{matlab_init}{2} causes \arg{Cmd} to be executed
whenever a new Matlab session is started.

    \predicate[nondet,multifile]{matlab_path}{2}{-Key, -Path:list(atom)}
Each user-defined clause of \predref{matlab_path}{2} causes the directories in \arg{Path}
to be added to the Matlab path of every new Matlab session. Directories
are relative to the root directory as returned by Matlab function proot.

    \predicate[nondet,multifile]{pl2ml_hook}{2}{+X:term, -Y:ml_expr}
Clauses of \predref{pl2ml_hook}{2} allow for extensions to the Matlab expression
language such that \verb|V[$X] = V[Y]| if \verb$pl2ml_hook(X,Y)$.

    \predicate[det]{ml_open}{3}{+Id:ml_eng, +Host:atom, +Options:list(_)}
\nodescription
    \predicate[det]{ml_open}{2}{+Id:ml_eng, +Host:atom}
\nodescription
    \predicate[det]{ml_open}{1}{+Id:ml_eng}
Start a Matlab session on the given host. If \arg{Host}=localhost
or the name of the current current host as returned by \predref{hostname}{1},
then a Matlab process is started directly. Otherwise, it is
started remotely via SSH. \arg{Options} defaults to []. \arg{Host} defaults to
localhost.

Start a Matlab session on the specified host using default options.
If \arg{Host} is not given, it defaults to localhost. Session will be
associated with the given \arg{Id}, which should be an atom. See \predref{ml_open}{3}.

Valid options are

\begin{description}
    \termitem{noinit}{}
If present, do not run initialisation commands specified by
\predref{matlab_path}{2} and \predref{matlab_init}{2} clauses. Otherwise, do run them.
\end{description}

\begin{description}
    \termitem{debug}{In, Out}
if present, Matlab is started in a script which captures standard
input and output to files In and Out respectively.

[What if session is already open and attached to \arg{Id}?]
\end{description}

    \predicate[det]{ml_close}{1}{+Id:ml_eng}
Close Matlab session associated with \arg{Id}.

    \predicate[det]{ml_exec}{2}{+Id:ml_eng, +Expr:ml_expr}
Execute Matlab expression without returning any values.

    \predicate[det]{ml_eval}{4}{+Id:ml_eng, +Expr:ml_expr, +Types:list(type), -Res:list(ml_val)}
Evaluate Matlab expression binding return values to results list \arg{Res}. This new
form uses an explicit output types list, so \arg{Res} can be completely unbound on entry
even when multiple values are required.

    \predicate[semidet]{ml_test}{2}{+Id:ml_eng, +X:ml_expr(bool)}
Succeeds if \arg{X} evaluates to true in Matlab session \arg{Id}.

    \predicate[det]{===}{2}{Y:ml_vals(A), X:ml_expr(A)}
Evaluate Matlab expression \arg{X} as in \predref{ml_eval}{4}, binding one or more return values
to \arg{Y}. If \arg{Y} is unbound or a single ml_val(_), only the first return value is bound.
If \arg{Y} is a list, multiple return values are processed.

    \predicate[det]{??}{1}{X:ml_expr(_)}
Execute Matlab expression \arg{X} as with \predref{ml_exec}{2}, without returning any values.

    \predicate[semidet]{???}{1}{X:ml_expr(bool)}
Evaluate Matlab boolean expression \arg{X} as with \predref{ml_test}{2}.

    \predicate[det]{ml_debug}{1}{+Flag:boolean}
Set or reset debug state. \verb$ml_debug(true)$ causes formatted Matlab
statements to be printed before being sent to Matlab engine.

    \predicate[det]{term_mlstring}{3}{+Id:ml_eng, +X:ml_expr, -Y:list(code)}
Convert term representing Matlab expression to a list of character codes.

    \predicate[det]{term_texatom}{2}{+X:tex_expr, -Y:atom}
Convert term representing TeX expression to a string in atom form.

    \predicate[semidet]{wsvar}{3}{+X:ws_blob(A), -Nm:atom, -Id:ml_eng}
True if \arg{X} is a workspace variable in Matlab session \arg{Id}.
Unifies \arg{Nm} with the name of the Matlab variable.

    \predicate[det]{dropmat}{2}{+Id:ml_id, +Mat:ml_loc}
Deleting MAT file from matbase.

    \predicate[det]{exportmat}{3}{+Id:ml_id, +Mat:ml_loc, +Dir:atom}
Export specified MAT file from matbase to given directory.

    \predicate[nondet]{matbase_mat}{2}{+Id:ml_eng, -X:ml_loc}
Listing mat files actually in matbase at given root directory.

    \predicate[det]{persist_item}{2}{+X:ml_expr(A), -Y:ml_expr(A)}
Convert Matlab expression to persistent form not dependent on
current Matlab workspace or MX arrays in Prolog memory space.
Large values like arrays and structures are saved in the matbase
replaced with matbase locators. Scalar values are converted to
literal numeric values. Character strings are converted to Prolog atoms.
Cell arrays wrapped in the \predref{wsseq}{1} functor are converted to literal
form.

NB. any side effects are undone on backtracking -- in particular, any
files created in the matbase are deleted.

    \predicate[det]{mhelp}{1}{+Name:atom}
Lookup Matlab help on the given name. Equivalent to executing help(`X).

    \predicate[det]{compileoptions}{2}{+Opts:list(ml_options), -Prefs:ml_expr(options)}
Convert list of option specifiers into a Matlab expression representing
options (ie a struct). Each specifier can be a Name:Value pair, a name
to be looked up in the \predref{optionset}{2} predicate, a nested list of ml_options
compileoptions :: list (optionset \Sbar{} atom:value \Sbar{} struct) \Sifthen{} struct.
NB. option types are as follows:

\begin{code}
X :: ml_options :- optionset(X,_).
X :: ml_options :- X :: ml_option(_).
X :: ml_options :- X :: list(ml_options).
X :: ml_options :- X :: ml_expr(struct(_)).

ml_option(A) ---> atom:ml_expr(A).
\end{code}

    \predicate[det]{multiplot}{2}{+Type:ml_plot, +Cmds:list(ml_expr(_))}
\nodescription
    \predicate[det]{multiplot}{3}{+Type:ml_plot, +Cmds:list(ml_expr(_)), -Axes:list(ml_val(handle))}
Executes plotting commands in \arg{Cmds} in multiple figures or axes as determined
by \arg{Type}. Valid types are:

\begin{description}
    \termitem{figs}{Range}
Executes each plot in a separate figure, Range must be P..Q where P
and Q are figure numbers.
    \termitem{vertical}{}
Executes each plot in a subplot;
subplots are arranged vertically top to bottom in the current figure.
    \termitem{horizontal}{}
Executes each plot in a subplot;
subplots are arranged horizontally left to right in the current figure.
    \termitem{\Sdot}{Type, [link(Axis)]}
As for multplot type \arg{Type}, but link X or Y axis scales as determined by Axis,
which can be `x, `y, or `xy.
\end{description}

Three argument form returns a list containing the Matlab handles to axes objects,
one for each plot.

    \predicate[semidet,multifile]{optionset}{2}{+Key:term, -Opts:list(ml_options)}
Extensible predicate for mapping arbitrary terms to a list of options
to be processed by \predref{compileoptions}{2}.
\end{description}


\printindex
\end{document}