search

smiths / caseStudies

Case studies of (manual) documentation for scientific computing software
3 stars 2 forks source link

Symbol Ambiguity (E vs E) in SSP #98

Closed niazim3 closed 6 years ago

niazim3 commented 6 years ago

Moved the following over from #39:

E is used to denote both elastic modulus and interslice normal force, results in ambiguity (https://github.com/smiths/caseStudies/blob/220c839436f38aaf2c87c4020d0ca23a278fa6c0/CaseStudies/ssp/Documentation%20Files/SRS_SSP.tex#L166-L169)

The interslice force should have a subscript. This should help a bit with the ambiguity. In the long run, a symbol other than E should be used for the interslice force. E for Young's modulus is so standard that it would be a mistake to change it, but the interslice force can be with any a symbol, likely a different alphabetical character that isn't used elsewhere.

niazim3 commented 6 years ago

Would it be better to perhaps implement the new letter now instead of later?

$E$ is used quite often throughout the whole document, so a lot would need to be updated:

Interslice Normal force symbols:

Ambiguous occurrences:

Elastic modulus:

smiths commented 6 years ago

Okay, you have a good point about changing E now, instead of later. However, this does also involve updating the figure that shows the force E. There might come a day when Drasil automatically updates figures, but this would be in the distant future.

As far as a replacement for E, I suggest P. A standard textbook for slope stability (Das) uses P for the horizontal force. If that clashes with another symbol, I have also seen X used, although that introduces potential confusion between lower case x for the coordinate system and capital X for the force. Whatever symbol you choose to use, you will still need the subscripts, since the force is defined relative to the ith slice.

niazim3 commented 6 years ago

Lowercase p is used to denote pressure and capital P denotes resistive shear force.

Lowercase x is used to refer to X Ordinate and uppercase x is used to refer to Interslice Shear Force.

Some letters (uppercase and lowercase) that are available for use to be a symbol for the interslice normal force are : d, g, j, l, o.

That or another character (Greek) can be used?

smiths commented 6 years ago

Thank you for the investigation @niazim3. Let's use G. (For some reason Greek letters aren't used that often to denote forces.)

niazim3 commented 6 years ago

As for the figure update that is necessary, shall I

?

smiths commented 6 years ago

Rather than rename this issue, why don't you close it and create a new issue for updating the figure. We should eventually fix the figure, but it is a low priority, especially since redrawing the figure will take time. As far as I can tell the original source for the figure is missing, so that means building it from scratch. (I had a quick look at it and I don't think editing the current png file would be easy or satisfactory.) If we should redraw the picture, we should try draw.io. I've used it recently, and I believe we can save the xml (?) file for future editing.

As a temporary fix, rather than a note in the README file a note with the caption for the figure might be more effective. If we say that in the figure G has been relabelled as E, the document will technically be correct.

niazim3 commented 6 years ago

Should the note-under-the-figure change be propagated to Drasil? (Also, as a rule, should most changes for this repo be propagated to Drasil or is it better to inquire about each one?)

smiths commented 6 years ago

Yes and yes. 😄 This change, and future changes to the manual version, should be propagated to Drasil. If in doubt, or if there seems to be a potential problem, we should discuss it, but in general, we want the Drasil version and the manual case study version to match. At some point we will stop maintaining the manual versions, but Drasil isn't ready yet for this step.

niazim3 commented 6 years ago

This issue can now be closed.

smiths commented 6 years ago

Great.