Hands On With OpenCog

From OpenCog

This is an outline for an in-depth, hands-on OpenCog tutorial. It is meant to compliment and extend a fairly broad set of AtomSpace examples and demos located in the AtomSpace github repo. If you want to learn opencog, starting with those examples is a very good choice. It is assumed that you have at least a basic understanding of Unix commandline, with some background in scripting language programming.

You may also wish to check the OpenCog By Way of Wikipedia page to get some conceptual grounding.


The wiki-page below, and related pages are a WORK-IN-PROGRESS. Many of the lessons outlined below have not yet been created. We hope they will be. Most of the material referenced in the outline already exists, but it's scattered across other wiki pages, Github README files and examples. The goal of the Hands-On tutorials is to take all the material and present it in a systematic way.

If you actually create a tutorial wiki page corresponding to one of the entries on this page, please link to it from this page (treating this page as a "table of contents") and also add the page to the Hands On With OpenCog category. See also the Curation page on how to categorize wiki pages.

Getting Stared

After the first two lessons below, most readers are encouraged to jump directly to the examples presented in the main AtomSpace github directory. Those examples provide a complete and exhaustive demo of all the main features, as well as all the finer points of using the AtomSpace.

Lesson : Building OpenCog (Hands On)

How to download, build and install OpenCog.

Lesson : Getting Started with Atoms and the Scheme Shell

Scheme is the primary scripting language used in OpenCog. Its pretty stright-forward; using OpenCog and the AtomSpace does not require strong knowledge of Scheme. It can be used quite casually. But having at leas a basic acquaintance is very important.

Lesson : Manipulating Atoms in Python

Studying Python should be delayed until much later. Although most programmers know python, it is not the best way to work with OpenCog: it's awkward, and presents many difficulties. Skip on first reading.

Lesson : Manipulating Atoms in JSON

Graph visualizers and web apps are almost always written in javascript, and are happiest when exchanging JSON data. The CogServer provides a WebSockets network interface for these users. See the network server HOWTO for more info.

Lesson : Manipulating Atoms in C++

Accessing the AtomSpace and OpenCog in C++ is an advanced topic, and should be skipped on the first, second and third reading. System programmers creating new Atom types will need to know this stuff.

Searching, Querying, Inferencing, Chaining

Deep in it's heart, OpenCog holds the AtomSpace, which is a fancy in-RAM knowledgebase. It's designed to hold general "knowledge" in the form of a graph. That is, it is a graph database. It has far more features and functions than other graph databases, and so there's a lot to it, but thinking of it that way is a good way to start.

Lesson : The Pattern Matcher

Every good database requires a query language to search it and retrieve answers. Every good query language has a huge number of bells, whistles and features. The AtomSpace is no exception. The engine of the query langauge is the pattern matcher.

The above is a short tutorial covering a smattering of pattern matcher basics. A complete set of AtomSpace examples and demos, going into much greater detail than here, can be found in the GitHub AtomSpace examples folder. Please, please, please! go through those; they will give you a very good grounding.

Lesson : Adding New Atom Types

Many important atoms are both declarative and active: they can be used to declare knowledge, but also do things, when called upon. The prototypical example of this is the GreaterThanLink, which can be used to declare that one thing is greater than another. The axioms describing order are well-known: one can perform reasoning and inference with GreaterThanLink, because one knows what it means. It has a semantics to it. It's well-defined.

Yet, it is impossible to store all possible number-pairs in the AtomSpace. So if you need to know when some particular number is greater than some other number, you have to compute it algorithmically. So, GreaterTanLink does that too: under the covers, in hard-coded C++ code.

And so it goes. If you have some kind of data, and it describes knowledge, but the only way to describe it is with an algorithm, then you must create a new atom type for it, and you must write C++ code to implement it. (Sure call out to Python if you wish. Or ROS. Or your local GPU, cellphone tower of wifi hotspot.) Your new atom type can now be reasoned over, because it has a semantics, but it can also do useful computations, when needed.

Interacting with External Stuff

Lesson : Interacting with External Agents via ROS

ROS is the Robot Operating System. OpenCog is regularly used to control robots. This tutorial assumes you are already familiar with ROS.

Lesson : The OpenCog Visualizer

The general theory of OC Vizualization is here.

Lesson : Using StorageNodes

The AtomSpace is an in-RAM database. You just might want to sometimes write some of it out to disk, and save it for later. The most robust way to do this is to attach to a commonly available, industry standard database. They're great for managing data, and distributing it across clusters, and doing cloud-type things. The AtomSpace does not try to reinvent this wheel.

The AtomSpace has been designed with a generic "backend" layer, so that data can be saved to any database or sent to any remote server. A number of these have been tried. The one that works the best is RocksDB, and is implemented in the RocksStorageNode. Also available are the PostgresStorageNode for saving/restoring Atoms to a Postgres database, and the CogStorageNode for exchanging Atomes with other (remote) AtomSpaces.

Other database systems have been tried. Almost all of them add far too much overhead, and introduce serious bottlenecks. The key problem is that Atoms are small. Like, really, really small -- a few hundreds bytes, in RAM. Just about any copy of these bytes, any move, any format conversion, any serialization/deserialization is going to be pure overhead, as compared to the direct access of a few hundred bytes. Most databases are designed for storing large things, not small things. So it goes.

Lesson : Importing External Knowledge Sources

This requires a basic understanding of Using a Backing Store in OpenCog.


Lesson : Running MOSES for Automated Program Learning

Lesson : Using MOSES via the R Wrapper

  • give some simple examples here ... Mike Duncan can make this section !

Lesson : Exporting MOSES Models Into the Atomspace