Candid feedback on installing cantera

[Santosh Shanbhogue]

Dear admins,

I wanted to share my recent experiences while installing cantera. I had to help at least half a dozen students install cantera on both Windows and Mac OS. Many others have loaned a laptop from the university just to use cantera. They now carry two laptops with them

I think that the installation steps (and for good reasons and outside the control of admins) are *broken*. And I suggest we move to a more robust approach:

-- Create two sets of installation instructions - one for users and other for developers

-- For users, remove all instructions as is and replace with three simple steps : install Anaconda, then install cantera via the conda channel. The problem with this approach is how to integrate Matlab, which is the origin of 99% of the problem in a university setting. So the third step with contain OS-specific instructions on how to use Matlab with Cantera, and I have simple solutions for these as well

This works on 100% of the machines and given how the conda ecosystem is evolving, I see this approach as very stable. And because Anaconda has a huge user base, Continuum will sort out all OS specific issues before we even realize they exist. This is 90% of the battle

and please:

- remove the instructions on how to install for a Mac OS. There is no rhyme or reason for outdated stuff to be listed on the installation instructions page, unless for historical reasons. 

If you need help from any of the above steps, I am happy to help

To underscore the severity of the problem - I can't install Cantera on Windows 10 machine and Mac OS X machines with the instructions as listed. I have to tweak them substantially. 

A lifelong Cantera admirer,

Santosh

[Bryan W. Weber]

Santosh,

Thank you for the feedback. If you'd like to submit a PR for these documentation changes, it would be good to see a new structure, this is always something we're looking to improve. As far as splitting the documentation, I'm not sure what would be different for "regular" users vs. developers, in terms of install instructions. I also don't think this would be more robust, since we would have to maintain two sets of documentation, with more chance of them being out of date. We also do recommend that users install the Anaconda/Python interface, but as you say, this doesn't necessarily solve the Matlab interface. Some further questions:

1) Can you please be specific about what went wrong with the Windows 10 instructions? As far as I know, those instructions should be correct.

2) Can you please show the installation instructions for Windows with Matlab (I assume you mean also using Conda) that you have in mind?

3) The macOS instructions became out of date only about 2 weeks ago. with the release of SCons 3.0.0, and technically, they're only out of date for the Matlab install. I agree there is no reason to keep out of date instructions up, but we simply have not had time to update these docs yet.

Best,

Bryan

[Santosh Shanbhogue]

Bryan,

Here is what has consistently worked, for cantera with the Matlabi interface installed (I'm mixing actual code and pseudocode, but you get the idea):

For Mac OS:

- Download anaconda with python 2.7 and 64-bit

- install scons: conda install -c conda-forge scons=2.5.1

- install cantera: conda install -c cantera cantera

- exit the shell

- open shell, invoke bash and make sure that the python path now points to anaconda

- clone cantera git

- scons build python_toolbox=full, system_sundials=n, matlab_toolbox=y, matlab_path=/Applications/MATLAB_20XX

- scons test

- scons install

- open matlab

- add path('/usr/local/something_matlab_toolbox_that_cantera_outputs_at_the_end_of_install')

- setenv('PYTHON_CMD', '~/username/anaconda2/bin/python2.7')

- setenv('PYTHONPATH', '~/usr/local/something_python_that_cantera_outputs_at_the_end_of_install')

Save the last three steps to an m-file and run every time you open matlab. Or lookup instruction to place in startup file online

For Windows, again, with the MATLAB interface functionality:

- Download anaconda with python 2.7 and 32 or 64 bit depending on OS

- open the conda shell that is now in Start

- install cantera: conda install -c cantera cantera

- open My Computer -> yada yada -> and set PYTHON_CMD to point to anaconda's python executable 

- Now download the *.msi file from the cantera documentation page

- Run the cantera msi installer

- open matlab and do the three steps : add path, set python_cmd and pythonpath like in MAC OS

Save the last three steps to an m-file and run every time you open matlab. Or lookup instruction to place in startup file online

For Ubuntu:

I have not tried but will bet that equivalent steps involving Anaconda will work

You may think that some steps are redundant (e.g. in Windows why do the anaconda install and the msi install, the msi should suffice) but trust me, this does not work on all systems. I am not fully sure why, but I think it has to do with Dell's Win 10 installation. For assembled PC's and manually installing Windows via a CD/image the cantera installation instructions seem to work. There is also an issue if your user name is "John Doe" vs. "JohnDoe". The above steps work in all cases

When I said users vs. developers, I meant to say install the most stable release of cantera vs. compile from source. In Mac OS, you have no choice, but I think the distinction allows us to create OS-specific instructions for how to compile cantera. This dichotomy already exists in the instructions currently on the web-page, so I am not sure I understand why you think you will need two sets of instructions. I am in fact suggesting simplifying the steps. Why bother with *.whl files, downloading a very specific version of numpy, etc. Conda takes care of all this, as you too seem to agree with

And finally, I suggest doing away with Homebrew. It has been updated now and if someone has an existing installation of homebrew, you have to invoke sudo to fix it. Very dangerous. Not sure if a new Mac out of the box will need to do the same, but again, why bother. With Conda, you can completely do away with homebrew

If you think any of the above is good enough for updating the documentation, let me konw and I'll submit a PR. The reason I did not submit a PR is if you philosophically disagree on these steps, then I can save my effort

Thanks,

Santosh

--
You received this message because you are subscribed to the Google Groups "Cantera Users' Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to cantera-user...@googlegroups.com.
To post to this group, send email to canter...@googlegroups.com.
Visit this group at https://groups.google.com/group/cantera-users.
For more options, visit https://groups.google.com/d/optout.

[Ray Speth]

Santosh,

I think there is always room for improvement in the installation and compilation instructions, and the experience of helping new users get started is, as you are discovering, often the time when issues with these instructions are revealed.

While I'm generally quite happy with Conda, I don't think we should eliminate instructions for installing without using conda. One area that could use improvement is that conda should be mentioned as an option for installing many of the prereqs for compiling Cantera. I would note that there is probably some work that should be done in the case where Cantera is built within conda so that we actually install inside the Conda environment -- the way that this is done for the sake of building the conda packages is a bit of a hack right now.

For Windows, I think the instructions are quite clear that you need to install both the MSI and the Python package. All that the current instructions lack is something to point out that the Python package can be installed either via conda or using the second MSI installer. I also would like to know what doesn't work for you about the current Windows installation instructions.

The only parts of the compilation process that are really OS-specific are the installation of the prerequisites, which are already broken out into different sections in the compilation docs. I'm not sure what the purpose of distinguishing users from developers is -- I think the important distinction, which the instructions already make, is between people who need to compile Cantera and people who don't.

I'll admit that the Homebrew install issues are a bit of an irritant at present, but this is really all due to Matlab. I have no idea what you're talking about that has been updated and requires sudo to be fixed, and what is so dangerous about it. Aside from the present issues with the new version of SCons, I think Homebrew provides the one of the simplest methods for installing Cantera with the Matlab toolbox.

Of course, the devil's advocate in me would suggest that if you really want to simplify the installation process for your students, you should tell them to just use the Python interface, in which case the simple conda install will certainly suffice.

Also, can we tone down the hyperbole? There is a perfectly good rhyme and reason why there is outdated information in the documentation: All of the developers are volunteers and have a lot of other demands on their time.

Regards,

Ray

To unsubscribe from this group and stop receiving emails from it, send an email to cantera-users+unsubscribe@googlegroups.com.

[Bryan W. Weber]

Santosh,

Along with what Ray said, I wanted to follow up on a few of the specific points you made.

1) On macOS, why do you suggest installing the Python package with Anaconda, and also building the Python package during the build step? Then you set the PYTHONPATH to point to the newly built installation, so what was the point of the conda install?

2) On Windows, you write "in Windows why do the anaconda install and the msi install, the msi should suffice", but this is already known that the MSI is not sufficient if you want to use CTI files, which require a conversion script that is installed with the Python interface. I'm not at all sure what this would have to do with a specific manufacturer's way of installing Windows 10, and I would be very surprised if there were any issues due to this, or spaces in the user name. It is possible that some characters (e.g., Chinese or Korean) characters in the username would cause a problem, but this would most likely be a problem for the installer and not really something we could fix (also, see the changes that Ray made the other day https://github.com/Cantera/cantera/commit/0c0a38d4fe6465fde3f51f73ed6bf8fe47c9fd79). Can you be more specific about the problems you encountered? If there is something wrong, I'd really like to see it fixed.

3) I agree with what Ray said, that it would probably be valuable indicate that it is possible to install some of the dependencies (e.g., NumPy) with Conda. However, not everyone has or uses the Anaconda installation of Python, and for those people, we need to tell them how to install the dependencies that they need. If you would like to make a PR to add this information, please feel free!

4) I'm still not sure what you mean by splitting the documentation. We already have platform-specific compilation instructions, and we have platform-specific installation instructions. Is the only proposal you're making here to add that dependencies can be installed with Conda?

Best,

Bryan

To unsubscribe from this group and stop receiving emails from it, send an email to cantera-users+unsubscribe@googlegroups.com.

[Santosh Shanbhogue]

Bryan,

When I composed my feedback, it was from the point of view of what works. Sometimes the steps seem redundant. e.g. as you point out, why double install the conda package and then from the source separately. In a separate post, we partly discussed the  issue - where you suggested I install anaconda with the cantera package from the conda channel and then compile from source without the python interface, just to have the matlab interface. But this does not work.

So I too fully do not understand why a double install is needed, except for the reason that it works. This was my motivation for splitting the documentation for  users and developers. For users, we provide instructions that work but are may not necessarily be optimal (e.g. a 0.5 GB anaconda install + many other pacakges they may not need, etc)

But I agree with your's and Ray's view on the way things are. And so lets keep it that way. As such, by patching the scons issue, I am sure the Hombrew route will work eventually. And if users have an issue they will post a message here 

Regarding the Win 10 installation, I don't know what went wrong, but I got Cantera to install via the steps I suggested. So things are fine now. If the same issue pops up next time, I'll dig deeper and post the issue here. I don't think a patch/PR is needed at this point

Thanks for all the help,

Regards,

Santosh

To unsubscribe from this group and stop receiving emails from it, send an email to cantera-user...@googlegroups.com.

To post to this group, send email to canter...@googlegroups.com.
Visit this group at https://groups.google.com/group/cantera-users.
For more options, visit https://groups.google.com/d/optout.

--

You received this message because you are subscribed to the Google Groups "Cantera Users' Group" group.

To unsubscribe from this group and stop receiving emails from it, send an email to cantera-user...@googlegroups.com.

[Ray Speth]

Santosh,

> So things are fine now. If the same issue pops up next time, I'll dig deeper and post the issue here.

I think this touches on a key point -- there are only so many opportunities to try installing Cantera on a pristine system in order to test the instructions. While it's tempting to just do something that works and move on, this is also your only chance to dig into the problem and figure out how to fix the instructions for next time, especially at the meticulous level of detail that many new users need.

Regards,

Ray

To unsubscribe from this group and stop receiving emails from it, send an email to cantera-users+unsubscribe@googlegroups.com.

To post to this group, send email to canter...@googlegroups.com.
Visit this group at https://groups.google.com/group/cantera-users.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Cantera Users' Group" group.

To unsubscribe from this group and stop receiving emails from it, send an email to cantera-users+unsubscribe@googlegroups.com.