Copyright, License, Contact
===========================
Copyright ©2013 Franz All Rights Reserved
License: TBD
Author: Jianshi Huang (jianshi.huang@gmail.com)
Build Netica Shared Library on Linux
====================================
Assume you're using x86 64bit Linux.
Tested on Ubuntu 12.04 x8664
% gcc -shared -fPIC -INetica_API_504/src -LNetica_API_504/lib \
Netica_API_504/src/NeticaEx.c Netica_API_504/lib/64bit/libnetica.a \
-lm -lrt -lpthread -lstdc++ -o lib/libnetica.so.5.0.4
Development notes
=================
There're about 250 functions in Netica C API, and dozens of other
definitions. I used SWIG for generating the C API wrappers for
eliminating human mistakes and saving time. Due to SWIG's limitation,
a modified Netica header file and a hand-written patch are needed. The
good news is that C API support is mostly done (except Listener
functions which need callbacks, will add later).
The SWIG interface definition is pretty straightforward, I only need
to deal with output parameters. Note that there's a bug in SWIG that
'char** OUTPUT' will not be recognized. This is manually fixed in the
patch.
The header file needs fix as well. 'enum' without 'typedef' will not
be recognized by SWIG; In the form 'typedef struct <name> <alias>',
<name> will be used as lisp class name rather than <alias>. These are
manually fixed.
And I've found several bugs in CLisp's netica implementation and
RNetica.
As for Lisp-side API, it's a big task. CLisp only implements very
basic ones. These are ported in src/netica.cl. RNetica seems to be a
good reference, but still, it only implements 2/5 of the Netica API.
Compile SWIG interface
----------------------
% swig -allegrocl -nocwrap -identifier-converter \
identifier-convert-lispify -module netica.ffi \
-Iinclude src/netica.i
This will generate src/netica.ffi.cl file.
Manual modification
-------------------
- in src/netica.ffi.cl
Change (ff:allocate-fobject ':char :c)
to
(ff:allocate-fobject ':char :c *mesg-len-ns*)
NOTE: SWIG's support of string size doesn't seem working
Package structure
-----------------
- Package netica.ffi
is the low-level wrapper for Netica's C API
- Package netica
is for Netica's Lisp interface, and the demonstration of using the
low-level C API
- Package netica.demo
is for demonstration Lisp interface usage
User Guide
==========
C API support is almost done, getting familiar with C API usage is
important. Currently only several Lisp interfaces are implemented.
Use netica.cl as a reference for implementing your own Lisp interface.
It's likely you'll use both Lisp interface and C API.
You cannot have multiple netica instances, but you can call Netica API
from multiple threads.
All errors are checked and properly reported. Severe errors are
signaled (error), less severe ones are warned, messages are printed
out if *verbose* is true.
Basic usage
-----------
(load "defsystem.cl")
(load-system :netica :compile t)
...
(use-package :netica)
(setf *license* "<your license>")
(start-netica)
...
...
...
(close-netica)
Naming convention
-----------------
Currently Lisp convention is enforced. For example,
(in C) GetNodeNamed_bn ==> (in Lisp) get-node-named-bn
Calling convention
------------------
C functions may return multiple values by output parameters (pointer
arguments). Here are the conversion rules for output parameters.
- for scalar values (int*, double*, state_bn*, etc.) and strings
(char*), we will convert them to lisp values and return multiple
values. The output parameter will be removed from the function
signature.
- for other values like arrays (state_bn*, double*, etc.) and structs
(net*, node*, etc.), we will not return them as multiple values and
you need to pass them to the function. When function returns, values
passed in will get updated (so you need to hold them in variables).
Notes for using Netica's C API in Lisp
--------------------------------------
Use *null* for NULL.
Use (truep ...), (nullp ...) for testing.
Condition
---------
- netica-condition
- netica-error
Documentation
-------------
Please check the docstring of functions, or source file netica.cl.
TODO
====
- More Lispy interface
Current Lisp wrapper is minimal (ported from CLisp).
RNetica is a good reference.
- Return proper typed foreign pointers
For struct object, SWIG generates proper CLOS definitions
(subclass of foreign-pointer), but they're not used in function
return types.
So all non-primitive value returned is a foreign-pointer and the
type information is lost.
Need to fix SWIG.
- Add NeticaEx.h support or implement Lisp equivalent
Need to deal with varargs.
So porting to Lisp seems a better choice.
- Lisp callback support
Used only by Netica's listener API.
This will mark the full implementation of C API :)
- More tests and examples