Drasil: Report on the Devi branch

[szymczdm]

There are some trivial and non-trivial issues with the diffs between build and stable on the Devi branch. It's had a lot of updates made to it over the last few months (and I managed to merge master in fairly recently), but was never fully merged in.

I'm going to continue removing the trivial diffs, but then I need some help on figuring out what exactly is going wrong (or going right, but looking different) and how to fix it (some are strictly printing issues for the IMs, some are a bit more complicated issues, in one case there's an entire subsection missing).

Could you please give me a breakdown of the diffs, along with which are (in your opinion) trivial, and which ones are larger problems? I've taken a good look at GlassBR for sure, so you can see the relatively small number of diffs left there after all is said and done.

If you all want to work on it, great, if not, please self-select someone to take this on.

[elwazana]

@szymczdm

• GlassBR

  • Theoretical Models

    • Change in the descriptions (Non-trivial)
      -- Information is lost during the transition from paragraph form to bullet point form
      1. If one of the TMs is true both are true if one is false both are false
      2. The glass is considered safe if either is true (because if one is true both are true as above)
      Stable:
      
      Generated:
      

  • Data Definition

    • Change in the displaying of information (Trivial)
      -- Change in the format of equations (All DDs)
      Stable:
      
      Generated:
      
      --- Change in the format of the description of DD1
      Stable:
      
      Generated:
      

  • Instance Models

    • Change in Description of IM2-IM3 (Non-trivial)
      -- Information is lost during the transition from paragraph form to bullet form
      1. Lose of associated assumptions
      Stable:
      
      Generated:
      

  • Data Constraints

    • Missing entire subsection (Non-trivial)

[szymczdm]

That is excellent. I can already tell what needs to be updated :)

[elwazana]

@szymczdm I believe this is the last of the differences:

• Chipmunk

  • Specific System Description

    • Changed wording (Trivial)
      Stable:
      
      Generated:
      

  • Solution Characteristics Specification

    • Added link (Trivial)
      Stable:
      
      Generated:
      

  • Assumptions

    • Added links to various sections (DD, IM, TM, GenDefs, and LC) (Trivial)
      Stable:
      
      Generated:
      
    • Semi-descriptive names added for actual assumptions (Trivial)
      Stable:
      
      Generated:
      

  • TMs

    • Change in description (no significant lose of information) (Trivial) -> TM4
      Stable:
      
      Generated:
      
    • Change in description (Lose of information) (Non-Trivial) -> TM5
      1. Assumptions associated with TM removed
      Stable:
      
      Generated:
      

  • GenDefs

    • Section (used to be empty) -> Complete removal (Trivial)
      Stable:
      
      Generated:
      

  • IMs

    • Input/Output and input/output constraints added to tables (Trivial)
      Stable:
      
      Generated:
      
    • Information lost (Non-Trivial)
      1. Assumptions associated with IM removed
      2. Data Definitions associated with IM removed
      Stable:
      
      Generated:
      

  • DD

    • Missing Section (Non-Trivial)
  • Data Constraint
    
    
    
    • Missing Section (Non-Trivial)
    
    

[smiths]

Great summary @elwazana. I agree with almost all of your conclusions. However, there are a few points where I would like to add some information:

• TM4 - you characterize this as no significant loss of information, but the information that the origin is the axis of rotation is significant. Without the information that the origin is the axis of rotation, the origin cannot be determined.

• For GenDefs - I would prefer an empty section ("There are no general definitions") to complete removal. If the section is completely removed, the reader will not know whether we forgot it, or if it is empty. When following a template, it is better to have all sections and explicitly state when there is no relevant content.

[niazim3]

1. We can start working on the following changes to reduce discrepancies in the logs so it becomes easier to focus on the non-trivial changes:

Chipmunk:

• reinserting the empty General Definitions section
• update stable for the semi -descriptive names for the assumptions (the other examples no longer have assumptions listed as A1, A2, A3, A4...) which means this was a good change in the Devi branch

GlassBR:

• DD formatting (spacing, symbol = expr vs expr)

Should I work in the Devi branch? Branch off of the Devi branch that'll be branched back into the Devi branch? @szymczdm

---

1. 
   Would the addition of the text "entered by the user" from the stable description be considered trivial? Perhaps such text can be automatically appended to any variables that are present in lists of inputs or input data constraint tables?

[samm82]

TODO

Trivial

• [x] GlassBR DD equations #699
• [x] GlassBR DD1 format @samm82
• [x] Chipmunk SSD wording @samm82
• [x] Chipmunk SCS link @samm82
• [X] Chipmunk Assumptions links @niazim3
• [X] Chipmunk Assumptions descriptive names @niazim3
• [X] Chipmunk empty GenDefs section missing @niazim3
• [x] Chipmunk Input/Output and constraints in IMs @elwazana

Non-Trivial

• [x] GlassBR TMs @niazim3
• [x] GlassBR IM2/IM3 - information loss @niazim3
• [X] GlassBR Data Constraints missing @niazim3
• [x] Chipmunk TM4 - information loss @elwazana
• [x] Chipmunk TM5 - information loss @elwazana
• [x] Chipmunk Assumptions/DDs for IMs removed - information loss @elwazana
• [x] Chipmunk DDs missing @elwazana
• [x] Chipmunk Data Constraints missing

Note: This is a very bare-bones description of these issues - see above for full description

[samm82]

For the formatting of GlassBR DD1, should the DDs state if a quantity is unitless? @szymczdm @JacquesCarette

[JacquesCarette]

All definitions should have the correct units -- and be 'unitless' if that is the correct unit.

[szymczdm]

Just jotting this down since it was part of a face-to-face conversation which hasn't been written down.

@niazim3 Yes you (and the others) can work directly on the Devi branch.

[niazim3]

It is desirable for the missing information to reappear where it originally was, correct? So adding the information to a derivation for a particular model is not an optimal solution?

[smiths]

@niazim3, I'm not sure what the question is referring to, but moving information to the derivation might be okay. The original (manual) version isn't perfect. There might be a better way to summarize the information. If you have a better way to propose (equivalent is also okay), then let us know the details. If it is better, or just as good, we can change the manual version to match the generated version.

[niazim3]

I should've mentioned I was referring to the missing information documented above for, for example, the instance models.

Proposal:

What if we were to add a "Notes"/"Additional notes" field to the models in question (i.e. IMs, DDs, TMs) that was just [Sentence]?

https://github.com/JacquesCarette/Drasil/blob/bda79c7dae9c845c178e0c309dca68ec0f4bec4a/code/Example/Drasil/DocumentLanguage.hs#L188-L200

https://github.com/JacquesCarette/Drasil/blob/bda79c7dae9c845c178e0c309dca68ec0f4bec4a/code/Example/Drasil/DocumentLanguage/Definitions.hs#L139-L160

That way, if the extra information is not really derivation-related, it's not added to the derivations of the models and at the same time, the information is near the relevant symbols, units, descriptions, etc., making it hard for the user/reader to miss.

Although this is still hardcoding the information in, it is better than having the information lost, as @smiths mentioned earlier.

[smiths]

This sounds like a good idea to me @niazim3. I would like to see an example of what the new documentation would look like, before propagating the idea too far, but it sounds like you are on the right track. Maybe there will be something more clever that we can do in the future, but for now keeping the information through a Notes field makes sense.

[niazim3]

Thanks @smiths; I'm going to use GlassBR's calculation of capacity instance model as an example:

Current stable:

Currently generated:

Proposed change*:

• the row header can be called "Additional Notes" or just "Notes"

[JacquesCarette]

While we're at it, we might consider making the description back into a paragraph?

I notice we've lost the 'synonym' part of LR.

[niazim3]

The 'synonym' part of LR can be added as a sentence in the notes section for now. (Although, noticed that #166 and the design choices wiki makes it seem as if such information is something that would rather be foregone to avoid ambiguity.)

Is it standard practice to keep the Description as a paragraph? The list looks slightly easier to read, but that may be just my personal preference.

[JacquesCarette]

Paragraph or otherwise is a style issue. I kind of liked the table to be smaller -- and you find the current layout as easier to read. Which says to me that this should be an option! [Please file an issue]. For simplicity, we can keep things as is.

And hurray for the wiki! Ok, I now agree with my old self rather than the manual version [and my self of 14 minutes ago], let's forego synonyms!

[smiths]

The proposed Notes field looks good to me. (I also prefer the list version of Description. 😄)

Please go ahead and propagate the addition of the Notes field. You should probably create a new issue for this change.

[niazim3]

As of 07cc70e, the log for GlassBR no longer points to discrepancies between the generated and stable files that indicate that information is being lost.

Instead, the discrepancies are:

<               \item{$is\_safe1$ is true when calculated probability is less than tolerable probability (Unitless)}
---
>               \item{$is\_safe1$ is the true when calculated probability is less than tolerable probability (Unitless)}
390c390
<               \item{$is\_safe2$ is true when load resistance (capacity) is greater than load (demand) (Unitless)}
---
>               \item{$is\_safe2$ is the true when load resistance (capacity) is greater than load (demand) (Unitless)}
705a706,707
> \\ \midrule \\
> Notes & 
828a831,832
> \\ \midrule \\
> Notes & 
1186c1186
...

, which leads me to ask:

1. Are the empty "Notes" headings in the table alright? (i.e. should the generated version be copied into the stable version in this respect)

2. The "is the" automation has worked for all symbol descriptions so far, but it sounds awkward for the is_* variables. Should a new issue be opened for that and stable be updated for now to contain the awkwardly-worded descriptions?

[smiths]

Rather than an empty "Notes" entry in the table, can we display "not applicable" when there are no contents? If many of the "Notes" fields are empty, this might start to feel like a waste of space. In that case, it might be better to just not display this field when the content is empty.

As far at the "is the" goes, it is wrong to say "is the true." I think you will have to create an issue for this.

Glad to hear that the information is no longer being lost in the generated version. 😄

[JacquesCarette]

We should definitely not display empty Notes sections. Whatever the data-structure is for Notes should be such that being empty can be detected.

[niazim3]

@JacquesCarette @smiths So it would be ideal if no field is displayed if the content is empty, but for now saying "not applicable" when there are no contents is fine?

[JacquesCarette]

For Notes, yes. [This is not a blanket statement, as for some fields it would be an error if they are empty]

[elwazana]

@JacquesCarette @smiths I was wondering for the Devi branch, one of the last things to do for stable is to correct the spacing issue in the DDs of GlassBr.

Stable:

Generated:

Which of these if prefered? Also should this be an option the user can make similar to #724?

[JacquesCarette]

I definitely prefer the compact version. There are likely many more options for display that I would wish to implement before this one... if ever.

[niazim3]

I think we can mention this discrepancy in #724 and update stable to match the generated versions for now...
Or would it be better to change the spacing in the generated html version to be more compact? @JacquesCarette

[smiths]

I agree that the compact version is preferable. If the boxes get too big, we may have to deal with a box that is bigger than the page. This sounds like a headache we want to avoid.

[JacquesCarette]

I thought this was the LaTeX... in any case, it would be good to investigate the reason why it is not compact. If it is a trivial fix, do it. If it isn't, then open an issue (and accept the current sub-optimal version)

[elwazana]

Questions regarding Stable_vGenerated Chipmunk:

1.
@JacquesCarette Hello Dr. Carette, I made a change when adding Notes to the Chipmunk example was
de-capitalization of the titles:
https://github.com/JacquesCarette/Drasil/blob/46660f8943f5aafc703469a267ae5c312b62d5ac/code/stable/gamephys/Chipmunk_SRS.html#L1228

Was originally Newton's Second Law of Motion, I was just wondering if you guys have a preference for this?

2.
@smiths For the Chimpmunk differences between Generated and Stable, I wanted to ask which of the following you would like to have as the introductory paragraph for Data Definitions:

_This section collects and defines all the data needed to build the instance models._
vs.
_This section collects and defines all the data needed to build the instance models. The dimension of each quantity is also given._

[smiths]

@elwazana, as far as capitalization goes, we want it to be consistent. It is best if every title is capitalized with the same rules. Ideally, this would be a configurable parameter for the generated documentation.

As for the introductory paragraph for the data definitions, I like the first option. The point about the dimensions seems arbitrary and tacked on. If we are going to list the fields of the data definitions, we should list all of the fields. (This (listing all the fields) is something else that could conceivable be configurable, but it isn't a high priority. Maybe we would have an option of verbose versus not verbose?)

[JacquesCarette]

Agreed on all points.

[niazim3]

Just a few more changes originating from/discussed for the Devi branch were made in PR #743. Commit 19f3ea2 specifically changes the output from

to

(added indents). I don't think the indents can be removed without making changes to the .css files, so these changes can be kept or requested for updates at your discretion @szymczdm @JacquesCarette ...

Other than that, I believe this issue can be closed.

[JacquesCarette]

I do think the indents should be removed.

[smiths]

I agree that the indents should be removed. Other than that, it looks good.

Actually, can we make one small (I assume) change. Can the Notes field please come right after the Description field? The notes are going to be related to the Description. Also, ending with Source and RefBy is fairly standard at this point.

[niazim3]

Thanks for the feedback! The placement of notes has been updated as of commits
b032040...e1e9911.

I'm going to draw @halonazhao's attention to the above commits and comment, since she was updating the other examples in her branch for the addition of notes as well.

[smiths]

Looks good.