==================
==    INSTALL  ===
==================

In order to use this package, you have to get the following packages ready on your computer:

	1.	A compiler and a linker
	 		e.g. gcc, ld

	2.	Ipopt. 
			Download it from https://projects.coin-or.org/Ipopt
		
    3. 	Numpy
			http://numpy.scipy.org/	
	
	4.	Python.h
			Usually you can use apt-get install python-dev (Debian family) or 
			download the source code from python.org
			
When you have everything ready, compiling pyipopt is rather simple. You can just use

	make pyipopt

then 

	make install 
    
If you use make install, you might need to process with superuser privilege, as it will copy file to the Python directory 

[IMPORTANT]

    Although I try very hard to make Makefile as generic as possible, there might still be some env variables in the Makefile that do not match your computer's configuration. Therefore, you might want to verify that all the env variables in the Makefile are correctly set. 


==================
==      TEST   ===
==================

To see if you have pyipopy ready, use the following command under the pyipopt's directory. 

		python example.py
	
The file "example.py" contains a toy optimization problem. If everything is OK, pyipopt will invoke Ipopt to solve it for you. 
This python file is self-documented and can be used as a template for writing your own optimization problems. 

Pyipopt is a legitimate Python module, you can inspect it by using standard Python commands like "dir" or "help". All functions in pyipopt are well documented. 

Since Hessian estimation is usually tedious, Ipopt can solve problems without Hessian estimation. Pyipopt also supports this feature. The file "example.py" demonstrates the idea. If you provide the pyipopt.create function with an "eval_h" callback function as well as the "apply_new" callback function, Ipopt will delegate the Hessian matrix calculation to your function (otherwise Ipopt will approximate Hessian for you).


==================
= I HAVE AN ERROR=
==================

Before reporting any errors as bugs to me, please do the following steps to diagnose the error.
You might be able to fix it really quick if you know where the problem is. 

Step 1. [VERY IMPORTANT]

Pyipopt relies the C interface provided by Ipopt to do all the work. Therefore, you might want to check 
if your C interface is correctly installed. I do understand that some folks can actually run ipopt executable, but 
it doesn't mean that your Ipopt C Interface is correctly installed (as a library). 

A good way to check this is to go to the 

  $IPOPT_DIR/Ipopt/examples/hs071_c/ 

directory and issue a "make" to see if you can compile and run this toy example. 
Pyipopt, as you might know, uses the same mechanism this example uses to call ipopt via its C interface. 


Step 2: 

I list a couple of representative errors that may happen after 
passing Step 1. Please make sure that you have done Step 1 successfully, 
otherwise it is meaningless to do the following. 

--------------------------------------------------------
* Error:
	import pyipopt
	ImportError: can not find  libipopt.so.0

* Solution:
    find it and copy it to a folder that ld can access
--------------------------------------------------------


--------------------------------------------------------
* Error:
	import pyipopt
	ImportError: /usr/lib/libipopt.so.0: undefined symbol: _gfortran_XXX

* Solution: 
    check if your hs071_c example work. It is very likely that your ipopt library is not correctly compiled. 
--------------------------------------------------------


--------------------------------------------------------
* Error:
	import pyipopt
	ImportError: /usr/lib/libipopt.so.0: undefined symbol: SetIntermediateCallback

* Solution:
	SetIntermediateCallback is a function added since Ipopt 3.9.1. (see https://projects.coin-or.org/Ipopt/changeset/1830 )
	Make sure you have an Ipopt version >= 3.9.1
--------------------------------------------------------

--------------------------------------------------------
* Error:
	import pyipopt
	ImportError: /usr/lib/libipopt.so.0: undefined symbol: ma19ad_

* Solution:
	First, use 
		nm /usr/lib/libipopt.so.0 | grep ma19ad_ 
	to see if it is marked with U. It should. This means that libipopt.so.0 is not aware of libcoinhsl.so.0. You can fix this
	by adding -lcoinhsl in the makefile of pyipopt. It seems to me that this happens in the recent versions of ipopt. Eventually
	pyipopt will have a better building mechanism, and I will fix this soon. 
--------------------------------------------------------


--------------------------------------------------------
* Error:
	import pyipopt
	ImportError: /usr/lib/libipopt.so.0: undefined symbol: SomeKindOfSymbol
	
* Solution:
	I can assure you that it is NOT a bug of pyipopt. It is very likely that you didn't link the right package when compiling pyipopt. 
	First, use 
		nm /usr/lib/libipopt.so.0 | grep SomeKindOfSymbol
	to see if this symbol is indeed missing. Do a Google search to find the library file, and 
	add -lWhateverLibrary in the makefile of pyipopt. 
	
	Ipopt is built using various third-party libraries. Different machines may have different set of libraries. You should 
	try to locate these dependencies and indicate them when compiling pyipopt. This is just a limitation of dynamic linking libraries and 
	is not related to Pyipopt. Please do not report a missing symbol error as a "bug" to me unless you are 100% sure it is the problem  of pyipopt. 
--------------------------------------------------------


For bug report and other suggestions, please contact me at 

youxu AT wustl.edu (Change AT to @)

You can simply call me Eric.



