Home My Page Projects Code Snippets Project Openings diderot
Summary Activity Tracker Tasks SCM

SCM Repository

[diderot] Annotation of /tests/examples/README.md
ViewVC logotype

Annotation of /tests/examples/README.md

Parent Directory Parent Directory | Revision Log Revision Log


Revision 4640 - (view) (download)

1 : glk 4640 # Diderot Examples
2 :    
3 :     These examples demonstrate [Diderot language](http://diderot-language.cs.uchicago.edu),
4 :     recently described in a [VIS 2015 paper](http://people.cs.uchicago.edu/~glk/pubs/#VIS-2015).
5 :     New examples are being added here to help you learn how to use Diderot,
6 :     and to provide starting points for writing your own Diderot programs.
7 :     The instructions below end with cloning these examples, and compiling them with Diderot.
8 :    
9 :     Diderot is a new language, so patience and constructive engagement is appreciated.
10 :     You can help by testing and improving the instructions below on how
11 :     to build the Diderot compiler, trying out the example
12 :     programs and reporting any problems or confusion, or
13 :     contributing new example programs.
14 :     Join the [diderot-language](https://goo.gl/kXpxhV) Google group to communicate with us.
15 :    
16 :     The example programs are listed here in order from simple to more complex:
17 :    
18 :     * [`hello`](hello/): Hello world in Diderot
19 :     * [`heron`](heron/): A non-trivial program to find square roots, via Heron's method.
20 :     Demonstrates input variables, the stabilize method, and 5-argument lerp().
21 :     * [`unicode`](unicode/): Computes nothing, but comments include a Diderot Unicode cheatsheet,
22 :     with information about the operators that they represent.
23 :     * [`tensor`](tensor/): Demonstrates printing, indexing, and multiplication of
24 :     tensors, user-defined functions, and differentiation of a vector field.
25 :     * [`vimg`](vimg/): Viewing, within a window of specified location and orientation,
26 :     of an image or of some of its derived attributes. Demonstrates
27 :     having an image dataset as an input variable,
28 :     univariate colormapping,
29 :     a single-expression function defined with `=`,
30 :     and use of `evals` and `evecs` for eigenvalues and eigenvectors.
31 :     * [`fs2d`](fs2d/): For generating 2D synthetic datasets. Demonstrates computing on globals at
32 :     initialization-time and chained else-if conditionals.
33 :     * [`iso2d`](iso2d/): Sampling isocontours with non-interacting particles using
34 :     Newton-Raphson iteration. Demonstrates
35 :     strands calling `die`,
36 :     the `inside` and `normalize` functions,
37 :     and finding gradients with ∇.
38 :     * [`fs3d`](fs3d/): For generating a variety of interesting 3D synthetic datasets;
39 :     similar to but more complicated than [`fs2d`](fs2d/).
40 :     Demonstrates a user-defined function for doing quaternion to
41 :     rotation matrix conversion, and nested conditional expressions.
42 :     * [`mip`](mip/): For maximum-intensity projections through 3D volumes;
43 :     Shows a minimal example of setting up a camera and casting rays,
44 :     and also provides a setting for demonstrating how better reconstruction
45 :     kernels can make a rendering output be invariant with respect to the sampling grid.
46 :    
47 :     Some other directories contain supporting files:
48 :     * [`data`](data/): Small sample datasets that can't be generated by program.
49 :     * [`cmap`](cmap/): Colormaps
50 :    
51 :     ## Building Diderot and these examples
52 :    
53 :     #### (0) Get Cmake, autoconf, and creating $DDRO_ROOT
54 :    
55 :     CMake is needed to build Teem, and autoconf is need to configure the compilation
56 :     of Diderot. These utilities can be obtained via `apt-get` on Ubuntu/Debian Linux,
57 :     or via [Homebrew `brew`](http://brew.sh) on OSX.
58 :    
59 :     To get [Cmake](https://cmake.org):
60 :     * Linux: `sudo apt-get install cmake`
61 :     * OSX: `brew install cmake`
62 :     * In any case, the [CMake download](https://cmake.org/download/)
63 :     page includes "Binary distributions" that have the executable
64 :     `cmake` you'll need.
65 :    
66 :     To get the [GNU autoconf](http://www.gnu.org/software/autoconf/manual/autoconf.html)
67 :     tools (specifically <code>autoconf</code> and <code>autoheader</code>):
68 :     * Linux: `sudo apt-get install autoconf`
69 :     * OSX: `brew install autoconf`
70 :    
71 :     To keep things contained, you should create a directory (perhaps <code>~/ddro</code>)
72 :     to contain all the other software directories referred to below,
73 :     and set `$DDRO_ROOT` to refer to it:
74 :    
75 :     mkdir ddro
76 :     cd ddro
77 :     export DDRO_ROOT=`pwd`
78 :    
79 :     **All shell commands used here assume sh/bash syntax (rather than csh/tcsh).**
80 :    
81 :     #### (1) Get SML/NJ
82 :     The Diderot compiler is written in [SML/NJ](http://smlnj.org), so you'll
83 :     need to install that first. **You need at least version 110.77 to build Diderot.**
84 :     You can learn the version of the executable `sml` by running
85 :    
86 :     sml @SMLversion
87 :    
88 :     There are different ways of getting `sml`.
89 :    
90 :     **On OSX**, (using [Homebrew](https://brew.sh)). Assuming that `brew info smlnj`
91 :     mentions version 110.77 or higher, then
92 :    
93 :     brew install smlnj
94 :    
95 :     (possibly followed by `brew link smlnj`) should work.
96 :    
97 :     **On Ubuntu or Debian Linux**, `apt-get` may work to install a sufficiently recent
98 :     version. `apt-cache policy smlnj` reports what version you can get;
99 :     if that's at or above version 110.77, you can:
100 :    
101 :     sudo apt-get install smlnj
102 :     sudo apt-get install ml-lpt
103 :     The second `apt-get` to get `ml-lpt` is required because without it, the later compilation
104 :     of the Diderot compiler (with the `sml` from `apt-get`) will stop with an error message
105 :     like `driver/sources.cm:16.3-16.18 Error: anchor $ml-lpt-lib.cm not defined`.
106 :    
107 :     **To install from files at http://smlnj.org**:
108 :     On the SML/NJ [Downloads](http://smlnj.org/dist/working/index.html)
109 :     page, go to the topmost "Sofware links: files" link
110 :     (currently 110.79) to get files needed to install SML/NJ on your platform.
111 :     On OSX there is an installer package to get executables.
112 :    
113 :     Or, you can compile smlnj from source. Doing this on a modern 64-bit
114 :     Linux machine requires support for 32-bit executables, since
115 :     `sml` is available only as a 32-bit program. You will know you're missing
116 :     32-bit support if the `config/install.sh` command below fails
117 :     with an error message like "`SML/NJ requires support for 32-bit executables`".
118 :     How you fix this will vary between different versions of Linux;
119 :     please tell us any specific steps you learn for your specific Linux flavor.
120 :    
121 :     * On Ubuntu: [`sudo apt-get install gcc-multilib`](http://stackoverflow.com/questions/23182765/how-to-install-ia32-libs-in-ubuntu-14-04-lts-trusty-tahr) (tested on 14.04 and 15.10)
122 :    
123 :     Then, to compile `sml` from files at http://smlnj.org (the `wget` command
124 :     is specific to version 110.79; there may now be a newer version):
125 :    
126 :     mkdir $DDRO_ROOT/smlnj
127 :     cd $DDRO_ROOT/smlnj
128 :     wget http://smlnj.cs.uchicago.edu/dist/working/110.79/config.tgz
129 :     tar xzf config.tgz
130 :     config/install.sh
131 :     export SMLNJ_CMD=$DDRO_ROOT/smlnj/bin/sml
132 :     Once you believe you have `sml` installed, it should either be in your path
133 :     (test this with `which sml`), or, if you didn't do this when compiling `sml`
134 :     with the steps immediately above:
135 :    
136 :     export SMLNJ_CMD=/path/to/your/sml
137 :     This is required for subsequent Diderot compilation.
138 :    
139 :     #### (2) Get Teem
140 :     The Diderot run-time depends on [Teem](http://teem.sourceforge.net).
141 :     Teem is overdue for a release, but in the mean time you should build
142 :     it from source with CMake, because Diderot (and these examples) assume
143 :     the current source.
144 :    
145 :     It is best to build a Teem for Diderot that has *none* of the optional
146 :     libraries (PNG, zlib, etc) enabled. Experience has shown that
147 :     additional dependencies from Teem will complicate the linking that the
148 :     Diderot compiler does.
149 :    
150 :     To get the Teem source and set the
151 :     <code>TEEMDDRO</code> variable needed later, run:
152 :    
153 :     cd $DDRO_ROOT
154 :     svn co https://svn.code.sf.net/p/teem/code/teem/trunk teem-src
155 :     mkdir teem-ddro
156 :     cd teem-ddro; TEEMDDRO=`pwd`
157 :     Then, build Teem and install into `teem-ddro`:
158 :    
159 :     mkdir $DDRO_ROOT/teem-ddro-build
160 :     cd $DDRO_ROOT/teem-ddro-build
161 :     cmake \
162 :     -D BUILD_EXPERIMENTAL_APPS=OFF -D BUILD_EXPERIMENTAL_LIBS=OFF \
163 :     -D BUILD_SHARED_LIBS=OFF -D CMAKE_BUILD_TYPE=Release \
164 :     -D Teem_BZIP2=OFF -D Teem_FFTW3=OFF -D Teem_LEVMAR=OFF -D Teem_PTHREAD=OFF \
165 :     -D Teem_PNG=OFF -D Teem_ZLIB=OFF \
166 :     -D CMAKE_INSTALL_PREFIX:PATH=$TEEMDDRO \
167 :     ../teem-src
168 :     make install
169 :     To make sure your build works, try:
170 :    
171 :     $DDRO_ROOT/teem-ddro/bin/unu --version
172 :    
173 :     Note that we do **not** recommend adding this <code>teem-ddro/bin</code> to your path;
174 :     its not very useful.
175 :    
176 :     Instead, post-processing of Diderot output often generates PNG images, which means you'll
177 :     want a **separate** Teem build that includes PNG and zlib. You get this with:
178 :    
179 :     mkdir $DDRO_ROOT/teem-util
180 :     cd $DDRO_ROOT/teem-util; TEEMUTIL=`pwd`
181 :     mkdir $DDRO_ROOT/teem-util-build
182 :     cd $DDRO_ROOT/teem-util-build
183 :     cmake \
184 :     -D BUILD_EXPERIMENTAL_APPS=OFF -D BUILD_EXPERIMENTAL_LIBS=OFF \
185 :     -D BUILD_SHARED_LIBS=OFF -D CMAKE_BUILD_TYPE=Release \
186 :     -D Teem_BZIP2=OFF -D Teem_FFTW3=OFF -D Teem_LEVMAR=OFF -D Teem_PTHREAD=OFF \
187 :     -D Teem_PNG=ON -D Teem_ZLIB=ON \
188 :     -D CMAKE_INSTALL_PREFIX:PATH=$TEEMUTIL \
189 :     ../teem-src
190 :     make install
191 :     (The difference with the commands above is the `-D Teem_PNG=ON -D Teem_ZLIB=ON`).
192 :     To make sure this build includes the useful libraries, try:
193 :    
194 :     $DDRO_ROOT/teem-util/bin/unu about | tail -n 4
195 :    
196 :     The "Formats available" should include "png", and the
197 :     "Nrrd data encodings available" should include "gz".
198 :    
199 :     To add these Teem utilities to your path:
200 :    
201 :     export PATH=$DDRO_ROOT/teem-util/bin:${PATH}
202 :    
203 :     This will only have an effect for your current shell, you'll have to [take
204 :     other steps, depending your environment](https://www.google.com/search?q=adding+paths+at+login+unix),
205 :     to ensure that this path is added with every login.
206 :    
207 :     **Note** that `unu dnorm` is used by the Diderot compiler to assert a
208 :     canonical representation of orientation and meta-data in Nrrd arrays
209 :     to simplify and specialize how that information is incoporated into a
210 :     compiled Diderot program. You can run `unu dnorm` (perhaps followed
211 :     by piping into `unu head -`) on your own data to see exactly what it
212 :     will do, or to normalize the meta-data prior to compiling the Diderot
213 :     program (the normalization is idempotent by definition).
214 :    
215 :     #### (3) Getting Diderot (the various branches)
216 :    
217 :     **NOTE: As Diderot branches are merged, the names and URLs for these may change**
218 :    
219 :     At this point there are different branches with different functionalities;
220 :     work on merging them is ongoing. Any or all of them should be within `$DDRO_ROOT`:
221 :    
222 :     cd $DDRO_ROOT
223 :    
224 :     Every branch is available via an "svn co" command below.
225 :    
226 :     The **vis12** branch was created with a
227 :     [VIS'12](http://ieeevis.org/year/2012/info/call-participation/welcome)
228 :     submission in mind. That never happened, and the
229 :     [VIS'13](http://ieeevis.org/year/2013/info/vis-welcome/welcome) submission was rejected.
230 :     Still, this has become the most mature branch, though it lacks some features from other branches.
231 :    
232 :     svn co --username anonsvn --password=anonsvn https://svn.smlnj-gforge.cs.uchicago.edu/svn/diderot/branches/vis12
233 :    
234 :     The **vis12-cl** branch is the only one with a working OpenCL backend. The `diderotc`
235 :     compiler from the other branches may advertise a `--target=cl` option, but actually
236 :     it only works in the vis12-cl branch.
237 :    
238 :     svn co --username anonsvn --password=anonsvn https://svn.smlnj-gforge.cs.uchicago.edu/svn/diderot/branches/vis12-cl
239 :    
240 :     The **lamont** branch includes the implementation of strand communication.
241 :    
242 :     svn co --username anonsvn --password=anonsvn https://svn.smlnj-gforge.cs.uchicago.edu/svn/diderot/branches/lamont
243 :    
244 :     The **charisee** branch includes field "lifting", based on the EIN internal representation.
245 :    
246 :     svn co --username anonsvn --password=anonsvn https://svn.smlnj-gforge.cs.uchicago.edu/svn/diderot/branches/charisee
247 :    
248 :     **To configure and build** any of these branches, the steps are
249 :     the same. Run these commands inside any of the per-branch directories
250 :     (such as `$DDRO_ROOT/vis12/`):
251 :    
252 :     autoheader -Iconfig
253 :     autoconf -Iconfig
254 :     ./configure --with-teem=$TEEMDDRO
255 :     make local-install
256 :    
257 :     Note the use of the <code>$TEEMDDRO</code> variable set above, and the possible
258 :     (implicit) use of the <code>$SMLNJ_CMD</code> variable also described above.
259 :     As long as there are multiple branches in play, "make local-install" makes more sense than "make install".
260 :     If your build fails with an error message `anchor $ml-lpt-lib.cm not defined`, you're missing
261 :     the ml-lpt library, which you can get through your package manager (such as `sudo apt-get install ml-lpt`) or from the
262 :     [SML/NJ](http://smlnj.org/) download page.
263 :    
264 :     Once the build of the Diderot compiler is finished, you can check that it worked by trying:
265 :    
266 :     bin/diderotc --help
267 :    
268 :     #### (4) Get the examples:
269 :    
270 :     cd $DDRO_ROOT
271 :     git clone https://github.com/Diderot-Language/examples.git
272 :    
273 :     #### (5) Try compiling and running the "hello world" example [`hello`](hello/):
274 :    
275 :     cd $DDRO_ROOT/examples/hello
276 :     ../../vis12/bin/diderotc --exec hello.diderot
277 :     ./hello
278 :    
279 :     Running `./hello` should print "hello, world". Every Diderot program,
280 :     even this trivial one, produces an output file. `hello` created `out.nrrd`,
281 :     a container for a single int. We can check its contents with:
282 :    
283 :     unu save -f text -i out.nrrd
284 :    
285 :     which should show "42". If you've gotten this far, you have successfully
286 :     built Diderot, and compiled and run a Diderot program!
287 :    
288 :     #### (6) Try the rest of the examples
289 :    
290 :     The beginning of this README.md lists the examples in a sensible order for
291 :     reading and experimenting, from simple to complex (after [`hello`](hello/)
292 :     is [`heron`](heron/)). The idea is that later
293 :     examples build on ideas and features shown in earlier examples.
294 :    
295 :     If you use Diderot for your own research or teaching, please share it with
296 :     the [diderot-language](https://goo.gl/kXpxhV) Google group, and consider
297 :     adding some new examples here.
298 :    
299 :    

root@smlnj-gforge.cs.uchicago.edu
ViewVC Help
Powered by ViewVC 1.0.0