Documentation doesn't explain how to run with matlab (octave)

[yurivict]

It seems that documentation focuses on specific functions and doesn't cover topics like how to run it in the first place.

For example:

$ octave  flame1.m 
'flame1' is a script from the file /home/yuri/cantera/flame1.m

 FLAME1 - A burner-stabilized flat flame

    This script simulates a burner-stablized lean hydrogen-oxygen flame
    at low pressure.

Additional help for built-in functions and operators is
available in the online version of the manual.  Use the command
'doc <topic>' to search the manual index.

Help and information about Octave is also available on the WWW
at https://www.octave.org and via the help@octave.org
mailing list.
error: 'oneatm' undefined near line 13, column 13
error: called from
    flame1 at line 13 column 12

addpath /usr/local/lib/cantera/matlab was executed, so it isn't clear what's wrong, and the documentation doesn't help either.

[bryanwweber]

Hi! Thanks for reporting this. Can you mention which documentation you checked? The procedure for MATLAB setup is described in the platform-specific install instructions. I think in this case you'll need to also addpath that folder and any subfolders. Also, the output of scons install shows the install path for the interfaces, I think the MATLAB interface usually goes in /usr/local/share although I'm on my phone so I can't check.

[yurivict]

I clicked on the Documentation link on the website.

[bryanwweber]

Thanks for the link! How did you install Cantera? Did you check that folder you mentioned for the Cantera interface?

[yurivict]

I found the problem. addpath directory should be /usr/local/lib/cantera/matlab/toolbox, not /usr/local/lib/cantera.

[bryanwweber]

Great! So I don't think the API docs page should change, the Python documentation likewise doesn't list how to install the Python interface. How did you install the interface? Was the message from scons install clear?

[yurivict]

How did you install the interface?

Through the port/package.

Was the message from scons install clear?

Not really. Most importantly, when users install a package - they don't see messages printed by scripts. Then users look for the online documentation and it doesn't explain required additional steps.

With Python at least there are no additional steps, so this makes it easy.

[speth]

What port/package? Is this the FreeBSD package for which you are the maintainer? Your post on Cantera/cantera-website#154 (where this probably belongs as well) suggests that all that is necessary to install on FreeBSD is to run pkg install cantera. If that package is now compiling the Mex interface to be used with Octave, the either

1. it should install the toolbox in a directory that's naturally on Octave's search path; or
2. you should let us know what the appropriate installation instructions are that include setting the user's Octave path, since where that gets installed is up to the FreeBSD package, not us.

[yurivict]

I install Cantera through the FreeBSD port/package, but any packaging system would have the same problem.

Once users install the package, most wouldn't be able to figure out that some line needs to be added somewhere to enable its Matlab interface.

Any special steps that are required for users to begin using the package or it specific features need to be explained in the documentation,

[speth]

The Windows installation instructions explain how the user should set the Matlab path.

If I recall correctly, the macOS installer automatically adds the correct directory to the Matlab path.

For other platforms, we don't provide packages for the Matlab toolbox, so there's nothing to explain. And if you compile from source, the directory to add is going to depend on what options were specified, hence the reliance on the post-install message.

I do agree that if we're adding a page for FreeBSD instructions, it should list whatever the additional steps required are since you're taking the time to compile an interface for Octave.

[bryanwweber]

@yurivict It seems like this belongs in the installation instructions for FreeBSD then, so I'm going to migrate this over to the website repository. Please feel free to make a pull request to my branch, or a separate pull request, to add these instructions. Unfortunately, none of the main developers have a FreeBSD machine to test with.

[yurivict]

Does Matlab also require to add the addpath line to some file before the package can be used?

[bryanwweber]

Yes, usually it can go in startup.m, or using the GUI interface you can add the appropriate folder, which I think adds it to some system directories.

[bryanwweber]

@yurivict Do you plan to add these instructions for FreeBSD?

[yurivict]

The FreeBSD port already runs with Octave - no instructions are needed there.

[bryanwweber]

Thanks @yurivict I'll close this issue then. Please feel free to reopen if there is something that still needs to be done here