% README
% This file is from Chemlogic, a logic programming computer chemistry system
% http://icebergsystems.ca/chemlogic
% (C) Copyright 2012-2016 Nicholas Paun

Contents

1. Usage and Installation
2. Dependencies
3. Features
4. Documentation
5. Changelog
6. Further Research and Development
7. License
8. Acknowledgements
9. Contact

1. Usage and Installation

Chemlogic comes with two interfaces: a command-line interface and a Web interface.

To run the CLI:

1. cd cli/
2. ./chemcli

The CLI implements an extemely simple DSL for querying chemical information (a help message will appear when chemcli is run). It is also a Prolog top-level (shell), so you program more complicated things.

To run the Web interface:

1. cd web/
2. ./chemweb

The Web interface runs on port 8000 by default, at http://localhost:8000/chemlogic/. The Web interface provides a simple interface for all of the Chemlogic features.

To compile the interfaces, use make:

1. make <interface>
2. make install
   Run make help for more details.

<interface> is either cli or web, or all to build both interfaces.

The program will be installed by default to /usr/local. This can be changed by passing PREFIX=<directory> to make to install Chemlogic under a UNIX-style filesystem structure or by passing DEST=<directory> to install all Chemlogic files to the specified directory.

NOTE: These options must be specified when running both the build and install targets, if they are run separately.

The executables built are still dependent on a copy of SWI-Prolog.

NOTE: If the fact/ database is edited, the program must be re-compiled.
NOTE: The Web interface will automatically search for its style files in <PREFIX>/share/chemlogic, or if it is not found, the current directory.

The Web interface can also be compiled as a UNIX daemon, by running make web-daemon

2. Dependencies

Chemlogic is written in Prolog and requires a Prolog interpreter. The code is mostly conformant with ISO Prolog and requires DCG features and the CLP(q) library. The Web interface depends on SWI-Prolog and is built using the Web framework.

Prolog distributions:

• SWI-Prolog: Developed and tested on this platform. (See http://www.swi-prolog.org/ for information.)
• YAP, CIAO and XSB Prolog: Will probably work.
• GNU Prolog: Might work, but CLP(q) must be ported.
• Prolog Cafe, tuProlog and GNU Prolog for Java: Will not work (tested). Signficant parts of the ISO standard are missing or incorrectly implemented.

3. Features

• Chemical formulas (incl. hydrates)

• Chemical names

  • Retained names
  • Acids
  • Ionic compounds
  • Covalent compounds
  • Some organic compounds
  • Pure substances/allotropes
  • Common names

• Symbolic equations

• Word equations

• Stoichiometric calculations

  • Limiting reactant analysis
  • Excess quantity calculations
  • Support for concentration units

• Reaction type analysis

  • Completion of neutralization, double replacement and single replacement reactions.
  • Predicts whether reactions of any of the above types will occur (using the reactivity series.)
  • Identification of neutralization, double replacement, single replacement, decomposition and synthesis reactions.

4. Documentation

See the docs/ directory. Documentation (the Chemlogic papers) is available in PDF.

5. Changes

• Version 2.0.1 (minor bugfixes and UI tweaks)
  • Corrected various incorrect outputs involving single elements and hydrates
  • Added placeholders and clearer messages to the web interface.

• Version 2.0
  • Added support for reaction type analysis (identification, completion and prediction)
  • Added support for stoichiometric calculations (incl. limiting reactant analysis, concentration calculations)
  • Developed an Android user interface (packaged separately)
• Version 1.0
  • First release

6. Further Research and Development

See TODO.md in this directory.

7. License

This program is licensed under the GNU Affero GPL v. 3, which requires modifications to programs offered publically as network services to be released. See LICENSE.

If this requirement is inconvenient, please contact me.

8. Acknowledgements

I would like to thank the many people who gave advice and helped with the project.

I am particularly grateful for the valuable assistance provided by Dr. Peter Tchir, my Physics, Chemistry and, now, Computer Science teacher. His help and advice, especially with algorithms and his support for my Computer Science projects helped make this program possible.

9. Contact

Nicholas Paun np@icebergsystems.ca, http://icebergsystems.ca