comparison pldoc/plml.tex @ 2:546bfd3988b0

Added unpolished pldoc documentation.

+\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}