Document c++ interface

[DiamonDinoia]

@mreineck we now have a pure c++ interface.

I think we should document it even if it is marked as experimental and unstable we can start testing it and receive feedback on it.

[mreineck]

I'm excited and slightly worried about this at the same time...

The main open issue I see with the C++ interface is that it communicates warnings/errors via return codes, which is not idiomatic at all. Especially in the constructor we have to jump through a lot of hoops to still support the original C interface:

  FINUFFT_PLAN_T(int type, int dim, const BIGINT *n_modes, int iflag, int ntrans, TF tol,
                 finufft_opts *opts, int &ier);

The ier variable is necessary just to get a return value out of the constructor, which I feel bad about.

I'm not sure we can present this to end users in this state.
There are other aspects (perhaps converting pointers to single objects into references, making more members of FINUFFT_PLAN_T private ...), but I think they are minor in comparison and I'm happy to work on those during the next weeks. But I'm not sure about the error reporting.

In principle I can replace almost everything with exceptions (and keep the C interface unchanged), but there's nothing I can do about the constructur warning "you have requested a too small epsilon, but I'm continuing nonetheless".
Do you have any suggestions?

[DiamonDinoia]

Yes, we can wrap FINUFFT_PLAN_T into finufft_plan as a member. Then we can throw an exception in the constructor.

This also allows for changing FINUFFT_PLAN_T to accomodate c-style functions with no impact to the cpp-interface.

If we believe that eps too small should crash the nufft.

I am drafting the cmake structure of what I think is best and we can take it from there.

[ahbarnett]

I still think warnings to stdout are useful. I don't want eps too small to crash FINUFFT, just run and report a warning. An opt turns warnings off. What is the idiomatic C++ way to return a "status code" from a function, that may not indicate error, just a warning, or diagnostics? I don't really want the user to have to interact with another "status object". Hence, the simple ier int value. Why not have FINUFFT_PLAN_T throw errors in C++ style, but still pass back int &ier also, which can allow warnings to be indicated (up to user to check ier then)?

…

On Fri, Jan 31, 2025 at 2:22 PM Marco Barbone ***@***.***> wrote: Yes, we can wrap FINUFFT_PLAN_T into finufft_plan as a member. Then we can throw an exception in the constructor. This also allows for changing FINUFFT_PLAN_T to accomodate c-style functions with no impact to the cpp-interface. If we believe that eps too small should crash the nufft. I am drafting the cmake structure of what I think is best and we can take it from there. — Reply to this email directly, view it on GitHub <#623 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACNZRSTK23PR2MRDKOWVARL2NPEOVAVCNFSM6AAAAABWH6IHVOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDMMRYGEZDKOJXGQ> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

-- *-------------------------------------------------------------------~^`^~._.~' |\ Alex Barnett Center for Computational Mathematics, Flatiron Institute | \ http://users.flatironinstitute.org/~ahb 646-876-5942

[DiamonDinoia]

Not sure. A warning is generally a print to std:cerr.

I have seen using the factory pattern with std::expected otherwise, but that is c++23.

Using int is c-style, I agree with @mreineck , I do not think we should use ier in c++. It feels weird.

Maybe a make_nufft function that returns a plan is not a bad idea. I think we need to prototype a bit. Not ready for 2.4.

edit:
variant are c++17, should we already use a factory mechanism? This way the interface will be forward is compatible.

[DiamonDinoia]

@mreineck this is how more or less I see the API: https://github.com/DiamonDinoia/finufft/tree/documenting-cpp-interface

The issue is that I need to make the namespace work in the .cpp which I am not sure how to go about it as of now. Open to ideas.