diff --git a/README.rst b/README.rst index 87d465f3..9ffde244 100644 --- a/README.rst +++ b/README.rst @@ -9,25 +9,86 @@ contains the necessary runtime support -- several class definitions and about 30 small everyday functions, such as ``length``. -This matlab program ``solver.m`` was taken from the matlab -programming competition in 2004 (Moving Furniture). To the -right is ``a.py`` -- its SMOP translation to python. +Example: ``solver.m`` + The matlab program ``solver.m`` was taken from the matlab + programming competition in 2004 (Moving Furniture). To the + right is ``a.py`` -- its SMOP translation to python. + Though only 30 lines long, this example shows many of + the complexities of converting matlab code to python. + .. code:: matlab 01 function mv = solver(ai,af,w) 01 def solver_(ai,af,w,nargout=1): 02 nBlocks = max(ai(:)); 02 nBlocks=max_(ai[:]) 03 [m,n] = size(ai); 03 m,n=size_(ai,nargout=2) + +==== ======================================================== + 02 Matlab uses round brackets both for array indexing and + for function calls. To figure out which is which, + SMOP computes local use-def information, and then + applies the following rule: undefined names are + functions, while defined are arrays. +---- -------------------------------------------------------- + 03 Matlab function ``size`` returns variable number of + return values, which corresponds to returning a tuple + in python. Since python functions are unaware of the + expected number of return values, their number must be + explicitly passed in ``nargout``. +==== ======================================================== + +.. code:: matlab + 04 I = [0 1 0 -1]; 04 I=matlabarray([0,1,0,- 1]) 05 J = [1 0 -1 0]; 05 J=matlabarray([1,0,- 1,0]) 06 a = ai; 06 a=copy_(ai) 07 mv = []; 07 mv=matlabarray([]) + +==== ======================================================== + 04 Matlab array indexing starts with one; python indexing + starts with zero. New class ``matlabarray`` derives from + ``ndarray``, but exposes matlab array behaviour. For + example, ``matlabarray`` instances always have at least + two dimensions -- the shape of ``I`` and ``J`` is [1 4]. +---- -------------------------------------------------------- + 06 Matlab array assignment implies copying; python + assignment implies data sharing. We use explicit copy + here. +---- -------------------------------------------------------- + 07 Empty ``matlabarray`` object is created, and then + extended at line 28. Extending arrays by + out-of-bounds assignment is deprecated in matlab, but + is widely used never the less. Python ``ndarray`` + can't be resized except in some special cases. + Instances of ``matlabarray`` can be resized except + where it is too expensive. +==== ======================================================== + +.. code:: matlab + 08 while ~isequal(af,a) 08 while not isequal_(af,a): - 09 bid = ceil(rand()*nBlocks); 09 bid=ceil_(rand_() * nBlocks) + 09 bid = ceil(rand*nBlocks); 09 bid=ceil_(rand_() * nBlocks) 10 [i,j] = find(a==bid); 10 i,j=find_(a == bid,nargout=2) - 11 r = ceil(rand()*4); 11 r=ceil_(rand_() * 4) + 11 r = ceil(rand*4); 11 r=ceil_(rand_() * 4) 12 ni = i + I(r); 12 ni=i + I[r] 13 nj = j + J(r); 13 nj=j + J[r] + +==== ======================================================== + 09 Matlab functions of zero arguments, such as + ``rand``, can be used without parentheses. In python, + parentheses are required. To detect such cases, used + but undefined variables are assumed to be functions. +---- -------------------------------------------------------- + 10 The expected number of return values from the matlab + function ``find`` is explicitly passed in ``nargout``. +---- -------------------------------------------------------- + 12 Variables I and J contain instances of the new class + ``matlabarray``, which among other features uses one + based array indexing. +==== ======================================================== + +.. code:: matlab + 14 if (ni<1) || (ni>m) || 14 if (ni < 1) or (ni > m) or (nj<1) || (nj>n) (nj < 1) or (nj > n): 15 continue 15 continue @@ -38,7 +99,7 @@ right is ``a.py`` -- its SMOP translation to python. 20 [ti,tj] = find(af==bid); 20 ti,tj=find_(af == bid,nargout=2) 21 d = (ti-i)^2 + (tj-j)^2; 21 d=(ti - i) ** 2 + (tj - j) ** 2 22 dn = (ti-ni)^2 + (tj-nj)^2; 22 dn=(ti - ni) ** 2 + (tj - nj) ** 2 - 23 if (d0.05) 23 if (d < dn) and (rand_() > 0.05): + 23 if (d0.05) 23 if (d < dn) and (rand_() > 0.05): 24 continue 24 continue 25 end 25 26 a(ni,nj) = bid; 26 a[ni,nj]=bid @@ -47,45 +108,6 @@ right is ``a.py`` -- its SMOP translation to python. 29 end 29 30 30 return mv - -Though only 30 lines long, this example shows many of -the complexities of converting matlab code to python. - -==== ======================================================== -line -==== ======================================================== - 02 Matlab uses round brackets both for array indexing and - for function calls. To figure out which is which, - SMOP computes local use-def information, and then - applies the following rule: undefined names are - functions; defined, are arrays. ----- -------------------------------------------------------- - 03 Matlab function ``size`` returns variable number of - return values. In python, functions are usually unaware - of the expected number of return values. To solve this, - number of return values is explicitly passed in - ``nargout``. ----- -------------------------------------------------------- - 04 Matlab array indexing starts with 1, python starts with - zero. New class matlabarray derives from ndarray, but - exposes matlab array behaviour. ----- -------------------------------------------------------- - 06 Matlab array assignment implies copying; python - assignment implies data sharing. We use explicit copy - here. ----- -------------------------------------------------------- - 07 Empty matlabarray object is created, and then extended - at line 28. ----- -------------------------------------------------------- - 09 Matlab functions of zero arguments can be used without - the parentheses, such as ``rand``. ----- -------------------------------------------------------- - 10 Matlab function ``find`` returns variable number - of values, which is explicitly passed in `nargout`. ----- -------------------------------------------------------- - 12 Variables I and J contain matlab-style arrays. -==== ======================================================== - Command-line options --------------------