The GLYCAM Programmers’ Libraries

Introduction

GLYLIB is a set of libraries designed to facilitate highly creative programming involving molecular data. The libraries are written in plain C, mostly ANSI or POSIX compliant. Currently, the molecular data that are most supported come from computational chemistry, biochemistry, biophysics etc., and are particularly data associated with molecular mechanics or molecular dynamics.

These pages, like GLYLIB, will almost certainly never be finished.

The most important things for you to know about GLYLIB are:

  • GLYLIB is written almost exclusively on a crisis to crisis basis, mostly by people who are scientists and who may or may not know a lot about programming. We do our best to make things work: after all, we use these libraries ourselves. But, we can’t claim perfection. Usually, we can’t even claim completion…
  • License, Part 1: You may use all or any part of it for free, but see the next point.
  • License, Part 2: Whether your use is commercial or not, we are academics who live off of grants, so please reference us in some non-hidden location if you use it in code or executables, regardless of how you use or distribute them.

Here is a little more information about GLYLIB.

In our lab, we don’t just use computational chemistry; we help to develop it. Because of this, we frequently need to do things with our molecular data that aren’t already written into software (or aren’t easily available, etc.).  To put that another way, doing science typically means doing something that no one else has done before.  If your science involves computation, then there is relatively little chance that software has already been written for whatever it is you need to do.

To help make it easier to generate our own programs, we started building a library. Because we have been developing it for ourselves as needed, it only contains functions related to some task we have previously needed to perform. But, we think we’ve make it very easy to add functionality.

A few words about the design philosophy

Scientific software needs to give the correct answer or not give any answer.  For this reason, there are many little checks in the GLYLIB code.  Typically, a failed check will cause the program to terminate.  In some obviously less-important cases, a failed check will merely issue a warning.  Currently, we do not have a facility for disabling these aspects of the code.  We’re not sure we want them to be disabled.  But, if you generate a patch, we’ll consider it.  Just make sure they can’t get turned off without effort.

Since another focus is on making it easy to write new code, it won’t necessarily be true that GLYLIB is fast or efficient. In fact, if any part of GLYLIB is particularly fast, etc., then consider that a pleasant bonus.

The worst aspect of the coding is…

The memory allocation.  We use realloc far too often.  Changing that would require a huge rewrite.  Volunteers?

So… what do you get with GLYLIB?

Two things:

  • A reasonably intuitive programming infrastructure that mostly works.
  • You don’t have to start absolutely from scratch.

Think of GLYLIB as a programming equivalent of a breadboard and a box of electronic bits. It isn’t intended to make your final product, and maybe not even the prototype. But, it will help if you’re just tinkering around or need to try out an idea.

We decided to make it available to the rest of the world, just in case there might be someone out there who can use it.

Obtaining, Compiling, and Updating GLYLIB

Currently, GLYLIB only has full functionality in a Linux- or Unix-type environment.  A few debugging functions require GNU, otherwise the code is pretty basic.  However, there are some issues with, say, porting to Windows.  A student did that once.  It’s possible, but not pleasant.  There are some functions that are not, or were not at the time, implemented in all compilers.

To download and compile a copy

  1. You need to install git if you do not already have it.
  2. Use the “git clone” command below to make a local copy of the repository. If desired, change “GLYLIB” to some other name or leave it blank for the default “glylib”.
    $ git clone https://github.com/GLYCAM-Web/glylib.git GLYLIB
    

    You can also visit the repo on github at https://github.com/GLYCAM-Web/glylib.

  3. Compile the library.
    • The make command will produce a few warnings. Those can be safely ignored. The following set of commands will produce libraries for C and for C++.
      $ cd GLYLIB/lib ; make
    • If you only want the C library, use:
      $ cd GLYLIB/lib ; make justC
    • If you only want the C++ library, use:
      $ cd GLYLIB/lib ; make justCpp

To update your copy

cd GLYLIB ; git pull
cd lib ; make clean ; make

Adjust the final make command, as desired, per the instructions above.  You should also check out the README in the lib directory.

Documentation

The documentation is currently a little sparse. Feel free to write us and ask for help.

  • If you want to browse form and function, you can see the online documentation. Better documentation will be forthcoming. Astute readers will notice that we are just beginning to learn to use Doxygen.
  • There is also a PDF file containing a brief intro. This intro also contains the basic pointer information you need in order to use GLYLIB, with examples, etc.
  • For those who prefer to learn by example, check out the example program.
  • If you want to know how we check our work, or would like a suggestion regarding how to check your own work, see this page.

Referring to GLYLIB

If you need to cite or otherwise refer to GLYLIB, we recommend using the URL glycam.org/glylib rather than the URL of the page you are currently viewing.  This URL is preferable because it should always work.  Even if we change the site around radically, that URL should always point to the latest information about GLYLIB.  Similarly, use glycam.org/glylib_docs if you need to refer to the documentation.

If you have questions, comments, want to contribute, etc:

We realize the documentation isn’t great right now. We definitely welcome contributions to that or to the GLYLIB code itself. For either, send email to Lachele Foley (lachele@gmail.com) or to GLYCAM Help (glycam@gmail.com).