Review the new IMs section and add missing (useful) information

[szymczdm]

When updating the IMs (on @halonazhao's branch) the section has changed quite a bit. We need to be able to re-introduce any lost information (one example is pictured here):

Left is build, Right is stable.

Notice there is a paragraph missing. This section now has a number of issues which may need to be looked at more closely by @JacquesCarette, @smiths, and myself before we can actually proceed in fixing it. We need to know what the missing paragraph(s) actually mean.

[szymczdm]

#506 and #507 mention different aspects of this issue, but it appears to be the whole section which will need review, so I'm going to leave this up until each of those are closed and we've had a chance to review the IM section once again.

[smiths]

@szymczdm, I'm not sure if your example is from noPCM or SWHS.
The blurb of text "The goals GS1 to .. " should be in the build version as well as the stable version. The text is intended to orient the reader about the relationship between the different pieces of knowledge. This text is present in the SWHS example:

https://github.com/smiths/swhs/blob/master/docs/SRS/PCM_SRS.tex

It has been commented out of the noPCM example:

https://github.com/smiths/caseStudies/blob/c98949681bacdbf870030c774ccedcd6f67d8cd2/CaseStudies/noPCM/docs/SRS/SRS.tex#L1014-L1019

The text would have been commented out of the noPCM example because it isn't exactly right for this example. The text should have instead been updated for the noPCM example.

[elwazana]

@szymczdm Differences Report between Stable and Manual:

• SWHS

  • Table of Units

    • Different order of displayed symbols (Trivial)
      Stable:
      
      Manual:
      

  • Table of Symbols

    • Different order of columns (Trivial)
      Stable:
      
      Manual:
      

    • Unsure what this is but doesn't appear in the manual (non-trivial)
      Stable:
      
      Manual:

    • R {Aspect ratio} missing from stable (non-trivial)
      Stable:
      Manual:
      

  • IMs

    • Missing information paragraph (non-trivial)
      Stable:
      Manual:
      

    • Missing information in IM1 (non-trivial)
      1. Assumptions associated with the input and output of IM1
      Stable:
      
      Manual:
      
      2. Description is missing associated assumptions and constraints
      Stable:
      
      Manual:
      

    • Missing information about associated assumptions and DDs in the derivation (non-trivial)
      Stable:
      
      Manual:
      

    • Glitch (trivial)
      Stable:
      
      Manual:
      

    • Missing information for the output of IM2 (non-trivial)
      Stable:
      
      Manual:
      

    • Missing information in derivation of IM2 (non-trivial)
      Stable:
      
      Manual:
      

    • Additional A_C in inputs of all IMs (Unsure if this is a trivial error or is the tip of a larger problem)
      Stable:
      
      Manual:
      

    • Missing input in IM3 "T_W from IM1" (non-trivial)
      Stable:
      
      Manual:
      

    • Missing information about assumptions associated with description of IM3 (non-trivial)
      Stable:
      
      Manual:
      

    • Missing a lot of information in the description of IM4 including assumptions, DDs, and TMs (non-trivial)
      Stable:
      
      Manual:
      

[szymczdm]

Thanks for the great summary! I'll take a more in-depth look at it shortly. @smiths can you take a look as well and let me know if there's anything you'd reclassify (trivial/non-trivial) or consider a non-issue?

[smiths]

Excellent work @elwazana. Very thorough. The information lost between the manual and stable versions is worse than I expected. Good to know so that now we can fix it.

I agree with your summary, I only have a few additional points to add:

• MINFRACT is in the manual version, but in lower case, and it doesn't appear in the summary table of auxiliary constants, as it should. The table of auxiliary constants was inadvertently changed to match stable at one point, instead of the other way around. I will correct the manual version to use ALLCAPS, since this is the usual standard for constants. I'll also add the entry back to the Auxiliary constants table. The changes are reflected in: smiths/swhs@ced732a
  This issue was discussed in SWHS - Volume of PCM software constraint #451

• The aspect ratio (R) was discussed in PCM SRS - Software Diameter constraint makes no sense smiths/caseStudies#26 Changes were made to manual, but not propagated to Drasil. @halonazhao might be able to help with this. The LaTex for adding R was given in commit smiths/swhs@f68dc8e

• The derivation information was added for the energy balances as a consequence of our discussion about the thermal flux applying over the coil and the PCM. The commit where this information was added is given at smiths/swhs@2106695
  This was discussed in Missing "over area Ac" smiths/swhs#48

[smiths]

I think the key for this issue is to split it into separate issues. There is too much going on here to keep track. Unfortunately we cannot currently fix the Drasil version to match the manual version because of the referencing issues. We need to sort out #1029 first. In addition to the work that @halonazhao is doing, I will reclassify some of the TMs, DDs, etc. (I'll create a separate issue for this soon.) Once this is done, we can return to this issue.

[smiths]

I have gone through the SWHS example and identified GDs and DDs that should be reclassified. I will create an issue for this, but there aren't actually any problems with the imports (based on #1029) that these changes will fix. The changes will improve the conceptual integrity and consistency of the document, but they aren't necessary to proceed with this issue. (I don't think.)

[smiths]

All of the issue created to sort out this issue have been closed. There are too many details to go through it all again; I am going to assume that the process works and close this issue too.