Update PDL::PP documentation with info from Practical Magick guide

[d-lamb]

@drzowie and @karlglazebrook wrote a wonderful "missing manual" to PDL::PP a few years ago. The PDL::PP docs now contain a link to that article on arxiv.org, but it would be nice if somebody went and cleaned up PP.pod based on the knowledge to be gained in the Practical Magick guide.

[mohawk2]

As noted on #357, the Mandelbrot set demo code uses // as a Perl comment, which does not work. @drzowie / @karlglazebrook Is there a way to update the paper to correct that?

[marioroy]

Since this issue exist for updating the article, I like to share my experience as a reader. Has anyone tried selecting code from the article and pasting into your editor of choice? It requires one to search and replace all the quoting characters to the ones that Perl understands. :) It's such a nice article. Well, I eventually witnessed PDL and the cool Mandelbrot demonstration.

[mohawk2]

Since this issue exist for updating the article, I like to share my experience as a reader. Has anyone tried selecting code from the article and pasting into your editor of choice? It requires one to search and replace all the quoting characters to the ones that Perl understands. :) It's such a nice article. Well, I eventually witnessed PDL and the cool Mandelbrot demonstration.

Can you enumerate here any other places where the quoting or commenting needs updating? :-)

[marioroy]

This may not be complete, but went through the article twice. Code blocks pages 5-7, 13, 19-31, 33-36 using ’ and/or ” versus ' ". Code blocks pages 5-6 using // versus # in Perl section.

[mohawk2]

This may not be complete, but went through the article twice. Code blocks pages 5-7, 13, 19-31, 33-36 using ’ and/or ” versus ' ". Code blocks pages 5-6 using // versus # in Perl section.

Thank you!

There is also the point noted on the PerlMonks article (as updated) that pgswin should not be given the size argument that it is, because it now gets interpreted as a scaling-factor, and 600x the size of the 500x500 image is overly large.

[mohawk2]

My extract of things that are in the 2017 article not currently (to my knowledge) in PDL docs:

• it acts as a PDL overview, so it touches on dimensions and broadcasting (formerly known as "threading")
• it's wrong (on p3) about scalar ndarrays - they don't have 0 elements, but 0 dims (so 1 element)
• active vs broadcast dims is a nice distinction to use
• broadcasting rules for dims is nice (p4)
• PDL::PP, like the article, refers to generating XS which isn't entirely true anymore (spell out multi-C)
• steal the pp_mandel example as iterated on PerlMonks, though it might want pulling into its own tutorial (which might also be true of the "Game of Life" example in PDL::Broadcasting
• the "Dimensionality and the signature of an operator" is great and wants merging into PDL docs somewhere
• the [t] Pars docs need checking everywhere to make sure the multi-threading thing is very clear
• p10 type promotion
• p11 make sure list of all PP functions is complete
• hpp on p21 should use an OtherPar to set m
• the standalone module on p22 wants lifting into separate doc page
• p23 no #! needed
• p29 threadsafe temporaries are now implemented
• p30 check Inline::Pdlpp can/can't use PMCode
• p34 $SIZE(x) no longer write-only
• the RedoDimsCode section wants to be its own small tutorial
• the "dataflow" part from p36 could clarify that even so-called calculation ops have trans, but they're (for now - loop fusion) destroyed/evaluated immediately
• DOCOMPDIMS needs updating to new name
• PMCode works fine for dataflow operators (p38)
• has_badvalue is wrong (p42)

We need to review our intro docs, and also "the PDL book".

The "variable active dims" point suggests we need more-native index-set operations in PP. Maybe a signature of Pars => 'PARENT(i*); index(n=#i)'? cf "einops"

[drzowie]

This is really great, thanks for the detailed review and update Ed!

I do not have time to work on this in the near future but I am glad to supply LaTeX source code and support an updated revision of Practical Magick on ArXiV as well (with appropriate new authors) as needed.

Thank you so much for the ongoing support of PDL!

Cheers, Craig

On Feb 19, 2022, at 4:52 AM, mohawk2 @.***> wrote:

My extract of things that are in the 2017 article not currently (to my knowledge) in PDL docs:

it acts as a PDL overview, so it touches on dimensions and broadcasting (formerly known as "threading") it's wrong (on p3) about scalar ndarrays - they don't have 0 elements, but 0 dims (so 1 element) active vs broadcast dims is a nice distinction to use broadcasting rules for dims is nice (p4) PDL::PP, like the article, refers to generating XS which isn't entirely true anymore (spell out multi-C) steal the pp_mandel example as iterated on PerlMonks, though it might want pulling into its own tutorial (which might also be true of the "Game of Life" example in PDL::Broadcasting the "Dimensionality and the signature of an operator" is great and wants merging into PDL docs somewhere the [t] Pars docs need checking everywhere to make sure the multi-threading thing is very clear p10 type promotion p11 make sure list of all PP functions is complete hpp on p21 should use an OtherPar to set m the standalone module on p22 wants lifting into separate doc page p23 no #! needed p29 threadsafe temporaries are now implemented p30 check Inline::Pdlpp can/can't use PMCode p34 $SIZE(x) no longer write-only the RedoDimsCode section wants to be its own small tutorial the "dataflow" part from p36 could clarify that even so-called calculation ops have trans, but they're (for now - loop fusion) destroyed/evaluated immediately DOCOMPDIMS needs updating to new name PMCode works fine for dataflow operators (p38) has_badvalue is wrong (p42) We need to review our intro docs, and also "the PDL book".

The "variable active dims" point suggests we need more-native index-set operations in PP. Maybe a signature of Pars => 'PARENT(i*); index(n=#i)'? cf "einops"

— Reply to this email directly, view it on GitHub https://github.com/PDLPorters/pdl/issues/293#issuecomment-1045999502, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAJTGNXCJEL6JDL26AFZGBLU3577XANCNFSM4VIUB2UA. Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub. You are receiving this because you were mentioned.

[mohawk2]

I do not have time to work on this in the near future but I am glad to supply LaTeX source code and support an updated revision of Practical Magick on ArXiV as well (with appropriate new authors) as needed.

Great! Could you either email me the source code, or even (if it's only a couple of files) attach it here?

Thank you so much for the ongoing support of PDL!

Thank you for the kind words, and for the amazing stuff you and the others have made!

[zmughal]

We can also create a repository for the guide.

[zmughal]

Have you seen this: https://ar5iv.labs.arxiv.org/html/1702.07753? It is rendered using https://github.com/brucemiller/LaTeXML.

[mohawk2]

That looks really good! Although the lack of scrollbar (and maybe even a contents thing) are clearly improvable.

[mohawk2]

I was just looking up the article again, and noticed there was a "source" link. It offers a .tar.gz file which contains PP-description-v1.tex. I attach it in a .zip file because GH doesn't allow uploading .tex. PP-description-v1.zip