README

% 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>