Making mechanism for external library/user-supplied code

[yizhang-yiz]

From @yizhang-cae on July 11, 2018 15:32

Summary:

User may want to supplied his own C++ code and/or library. The compiling/linking may require special treatment. Stan needs a rule to treat this scenario.

Description:

User may want to supplied his own C++ code and/or library. The compiling/linking may require special treatment. Stan Math needs a rule to treat this scenario, and documentation and guide to help user understand the process.

Reproducible Steps:

n/a

Additional Information:

Provide any additional information here.

Current Version:

v2.17.0

Copied from original issue: stan-dev/math#934

[yizhang-yiz]

From @syclik on July 11, 2018 16:19

Can you provide a concrete use case / example?

We need to think of how much is the responsibility of the Math library to
get this linking correct. That said, my guess is that the external linkage
is not going to be the responsibility of the Math library. The Math
library's makefiles are only responsible for building tests. It's not used
to build executables for client code. Do you envision Math developers
needing to link other things for tests within the Math library? It might be
more appropriate at the CmdStan level.

On Wed, Jul 11, 2018 at 11:32 AM Yi Zhang notifications@github.com wrote:

Summary:

User may want to supplied his own C++ code and/or library. The
compiling/linking may require special treatment. Stan Math needs a rule to
treat this scenario.
Description:

User may want to supplied his own C++ code and/or library. The
compiling/linking may require special treatment. Stan Math needs a rule to
treat this scenario, and documentation and guide to help user understand
the process.
Reproducible Steps:

n/a
Additional Information:

Provide any additional information here.
Current Version:

v2.17.0

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
stan-dev/math#934, or mute the thread
https://github.com/notifications/unsubscribe-auth/AAZ_F2sFTW1vJH9ixZ8V2JU9xpH9QcPaks5uFhqfgaJpZM4VLXrJ
.

[yizhang-yiz]

Close to move to cmdstan

[yizhang-yiz]

From @bob-carpenter on July 12, 2018 22:15

This is super-convenient for moving issues: https://github-issue-mover.appspot.com

[yizhang-yiz]

Thanks @bob-carpenter.

[yizhang-yiz]

To answer @syclik 's question as to how Math can be used as standalone and how the external Makefile could look like in a real world problem, here's an example from my background. In this example, MITgcm is the external PDE solver, here's its makefile that utilizes fortran compilers. It's not very complicated, but still defines quite a few variables and settings that orthogonal from Stan's makefile. What I'm proposing here and in stan-dev/stan#2567 is to have a STAN_EXTERN_MAKEFILE in make to point to external makefile like this, should the user need to link Stan with his own solver. Conceptually it's different from usinglocal which deals with Stan's own settings.

Also an example of how Math could be used standalone, https://www.youtube.com/watch?v=vr-OgFJaT3g is a talk of using the above MITgcm with OpenAD to do adjoint sensitivity analysis. Though using different approaches, Math and OpenAD serve the same purpose, and I think that's the motivation of using it outside of Stan lang.

Hopefully this gives @syclik some background in addition to our chat.
EDIT: Here in the above talk is what I meant by PDE vs QoI in forward_pde function.

[bob-carpenter]

Sensitivity analysis with our math library is one standard application of autodiff. And Stan's getting more and more useful for that as we add better solvers and better matrix operations. We also intended it to be usable to develop new sampling and optimization algorithms. The math library can be used on its own, or with generated C++ from a Stan program. Hopefully the latter will get easier after we rebuild the class structure so a model class can be compiled independently of the solvers, matrix lib, etc.

[yizhang-yiz]

Yes. I was addressing @syclik 's concern as he mentioned that the Math library was not designed to be used out side of Stan, and its makefile is not intended to be making things other than tests.

[syclik]

Yes. I was addressing @syclik 's concern as he mentioned that the Math library was not designed to be used out side of Stan, and its makefile is not intended to be making things other than tests.

Sorry -- there's a large misunderstanding.

The Math library is designed to be used as a separate C++ library. The Stan library happens to be the one that drives most of the development, but it is designed to be used outside of Stan.

The Math makefiles are only there to build tests. There are no executables that are directly built from the Math library. It's like most of the other C++ packages. The user is responsible for including the header files and linking the libraries from their own build process (at the Math library). I think we can do a better job of explaining how to do that easily, but the instructions are all there in the wiki and the top level README.

[yizhang-yiz]

Sorry that I took wrong message from the chat. In that case do we need to address how MPI should be setup and built in Math? If a user tries to use Math to link his own library that utilizes MPI, he may have a bad time as we defaults to MPI_WORLD_COMM, and we don't specify how to make with various MPI and platforms.

This is just my concern as Math is not a header-only library anymore.

[bob-carpenter]

Yes, doc for how to enable and use MPI and multi-threading would be great. It'd be really nice to have a simple example C++ application that uses derivatives that can be used through the math library just so people can see if everything is working. A big problem we have for the math library is doc for the library itself. That's at two levels. At the lower level, there's function doc, which we may be able to share with the doc for the Stan language. Then there needs to be doc on how to compute derivatives. Part of that's in the arXiv paper, but it's not at all aimed at being practical from a user perspective.

[yizhang-yiz]

If it were all headers it'd be fine, otherwise ideally we should provide configure to poke system settings and user-specifications. It's supposed to be a good practice but nowadays library writers are getting lazy.

[bob-carpenter]

Making the math library easy to use standalone was never a priority. Partly because we didn't think we'd have the staff to support the doc and help and partly because it was very much in flux. I think we're in much better shape now to do the right thing. @yizhang-cae would you mind laying out what you think we should have in the way of doc in an issue? We can at least start ticking bits of it off. I actually like writing doc when I understand what I'm writing about.

[yizhang-yiz]

@yizhang-cae would you mind laying out what you think we should have in the way of doc in an issue?

stan-dev/math#941