Using the `transmute` feature

Users
1

Should an example of the use of the transmute feature be useful, one such example is to deliver the fractional and integral parts of a real(w) number, the modf() function in C. Returning the result as a tuple of two real(w) numbers, the integral component and the fractional component, the function called split() for want of a better name could be written as …

At this point I got confused with the new inferface - so I created issue #28188.

Is such an example worth pursuing? Either within documentation or as part of Math.chpl

New Issue: Stabilize transmute
New Issue: [Documentation]: Document transmute
2

Hi Damian,

Quick summary: oof, there's definitely a problem here, thanks for
bringing it up. Full summary of what I think we should do about it at
the end of my email.

Long version:

I'm not seeing documentation of transmute via a brainless search in our
documentation page, which feels a little like an oversight since the
name itself doesn't seem like something we would have intentionally
hid. However, its definition lives in ChapelBase rather than either of
the Math libraries, which I imagine accounts for some of why it was
hidden (whether intentional or not).

I think that means there's a couple of additional questions here:

  • Is transmute stable?
  • Should it be intended as user-facing?

And then depending on the answer to those, we get to your questions. I
think if at least one of the answers to those is true, it would
definitely be valuable to have a documentation example like what you
describe. My instinct would be either:

  • a user's guide entry, or
  • a blog post on the subject

where I'd probably default to a user's guide entry.

Returning to the questions I just posed, I think the answers are:

  • No, transmute is not stable. I'm not seeing any discussion about the
    stabilization of the feature, just
    https://github.com/chapel-lang/chapel/issues/14140 oriented around
    introducing it. It looks like it ultimately got added in 1.30, into the
    internal ChapelBase module. I think what happened here is a simple
    mistake - the HPE team had reviewed ChapelBase already (labeled as
    "Builtins" for those looking through old release notes), so considered
    the contents of it "stable" in 1.25.

That meant that we didn't go back through ChapelBase again before 2.0
(in part because there was just so much to be tracking and we were
already running longer into the stabilization process than we wanted to
be). Since we were also in the middle of the stabilization process, we
were still building muscle memory for labeling new things as unstable
or having design discussions oriented around trying to avoid making the
sorts of mistakes that we'd needed to make updates for. That said,
however, I haven't looked at its interface - being strongly in the
middle of the stabilization process means that we were probably actually
thinking about things like its arguments, whether it should be a method
or a standalone function, that sort of thing. It seems reasonable for
it to be something that is available by default - however, as you're
alluding to, it may be more appropriate for the AutoMath module than
ChapelBase (especially considering that ChapelBase/"Builtins" no longer
has an equivalent docs page, as its contents were either moved to
modules or into relevant spec pages). That seems like something for us
to discuss.

  • Yes, it absolutely should be considered user-facing. It was added
    based on requests from you and Bryant. However, it does not seem to
    turn up in our documentation (probably because it was added to
    ChapelBase and ChapelBase has always been a little funky about what gets
    transformed into documented code and what gets skipped). That
    absolutely should be rectified as well.

So, in summary:

  1. transmute does not seem to be documented at all. That should be fixed.
  2. it probably should also generate an unstable warning (or we should
    prioritize having a stabilization discussion around it so that we can
    skip that phase of its life)
  3. after that, it'd probably be friendly to have either a user's guide
    entry for it, or a blog post about it.

These seem like reasonable things to open issues about (and I think the
issue you've opened counts as "an issue for point 3"). I would address
this by adding an unstable label to the functions now, then adding the
basic documentation entry somewhere, then worrying about the rest of it
(since adding an unstable warning is very easy and it would be bad to
get other users relying on the feature when we might change it, even
though I strongly suspect they won't notice any changes we do make to it).

Thanks for noticing this, Damian!
Lydia

3

Thanks for that history.At the time, I was more interested in my own selfish needs which were about having it work with params.

The transmute() function works for my needs which are strictly a subset of its functionality. I think Brad was looking at eventually having slightly more functionality than what it has now. So that might mean that its interface is stable but that its documentation is unstable. Talk to him when he has a spare 5 minutes. I have no idea of Bryant's needs and application.

I can also provide a few more simpler examples of the use of transmute() that you can cherry-pick to go into any documentation. As a general rule, I would suggest that the average user avoids the transmute() routine and rather rely on low-level routines which wrap around it and hide it. The fully blown usage case seen in #28188 was just a way to get the ball rolling using easily described functionality, even if the code itself is a bit intricate.

You can also use transmute() to implement the routine which was the subject of our discussion of a few days ago, one use of which is to project a complex number onto the extended complex plane (not that I would use those words to describe what that particular routine does).

The description of transmute() is probably better done by Brad because he knows his future plans and his wording would probably better fit with the aura of other routines. My words would seem too focused on the introspection and manipulation of floating point numbers and transmute() is more than that.

4

Correction: it was added as unstable. I'm not sure how I got the
impression it wasn't, since that looks to have happened in the PR I
thought I looked at in order to determine it lived in ChapelBase ...
sorry about that mistake.

I've opened:

Thanks again for pointing this out!
Lydia