I'm writing a reproducible paper, and the paper has computational results that are generated by a Python script (a similar MATLAB script generates nearly identical results). I feel that the paper would be easier to understand for readers if they could match up the calculations in the paper with calculations in the code. The work proposes an abstract formalism, and the examples in the paper are supposed to make this formalism more concrete for readers (many of whom will be engineers); the code will probably be the most detailed record of how to perform the calculations, and making it clear could help us during the review process.
Does anyone have any suggestions on how to make the correspondence between code and computational results (figures, equations) more clear?
For instance, I was thinking that when it came to lines of code implementing various steps in the paper, I could cite equation numbers (it would be amazing if I could cross reference between the code and LaTeX, but hand-labeling them is fine), and I could write functions corresponding to the various examples and figures, such as
def example_1(): # Insert code corresponding to first example pass def figure_1(): # Insert code that generates Figure 1 pass
If the code were large, and I weren't trying to explain how a bunch of different mathematical methods used in engineering were actually the same, I probably wouldn't bother so much with making the code clear, but given the abstract nature of the paper and the small code base, it seems as though there could be value in this exercise.