Appending missing information to the Drasil side of the Documentation

[elwazana]

As was noticed in issue smiths/swhs#33 in the swhs repository, there appears to be missing information in the documentation, as per smiths/swhs#50 (comment).
I've fixed that over in the manual version of the docs, and I've started trying to fix them here in Drasil in a separate branch missingInfo.

However, I ran into a problem trying to append a sentence to the end of an equation.

Should be:

Stable has:

The problem is that the Data Definitions in SWHS in Drasil are defined as of type QDefinition, which doesn't take a sentence only a QuantityDict, an Expr, a References, and a Derivation. This may be a design issue in the way DataDefs are actually defined. The issue may be related to this comment in the DataDefs.hs file:

[smiths]

@elwazana, if it helps, I have no objection to the Ap information being given in the Description. It doesn't have to be part of the Equation.

[elwazana]

@smiths That's what I originally thought might fix the problem, but from what @niazim3 and I looked through, the description portion of the Data Definitions seems to be automatically generated based upon the symbols that are used in the equation.
So I'm not sure if I should wait for @szymczdm and @JacquesCarette cause that seems more their side of work?

[smiths]

This is what I was afraid of. The equations have more information associated with them than just their symbols. Yes, we will have to speak with @szymczdm and @JacquesCarette. For instance, we need to capture information about the derivation of equations and about the assumptions that are required for their validity. There may be a better place to put this information, but it has to go somewhere.

[smiths]

We have independently discovered the same problem as @szymczdm mentions in issue #522. At least we are updating the manual version so that this information will not be lost while we sort out the challenge of adding it to the GD.

[szymczdm]

Alright, looks like we need to modify the design a bit. This information should be captured as it is extremely relevant, yet it's not "usable" information right now. This leads me to believe the relevant pieces are missing somewhere "higher up the chain", so to speak.

[elwazana]

Documentation of missing information cases

1. Must add ", over area A_c" to the equation (or description) of dd1HtFluxC

2. Must add assumptions back into description of dd1HtFluxC for the derivation
   

   Drasil/code/Example/Drasil/SWHS/DataDefs.hs

   Lines 27 to 28 in 0e8d5f1

   	dd1HtFluxC :: QDefinition
   	dd1HtFluxC = mkDataDef ht_flux_C htFluxCEqn

3. Must add assumptions into the description of dd2HtFluxP
   

   Drasil/code/Example/Drasil/SWHS/DataDefs.hs

   Lines 35 to 36 in 0e8d5f1

   	dd2HtFluxP :: QDefinition
   	dd2HtFluxP = mkDataDef ht_flux_P htFluxPEqn

4. Missing constraint (0 < \phi < 1) in the equation of dd4MeltFrac
   

   Drasil/code/Example/Drasil/SWHS/DataDefs.hs

   Lines 47 to 50 in 0e8d5f1

   	dd4MeltFrac :: QDefinition
   	dd4MeltFrac = fromEqn' (melt_frac ^. uid) -- FIXME Should (^. id) be used
   	(melt_frac ^. term) (S "fraction of the PCM that is liquid")
   	(eqSymb melt_frac) melt_frac_eqn []

5. Missing initial case Q(0) = 0 for ODE latHtEEqn
   

   Drasil/code/Example/Drasil/SWHS/TMods.hs

   Lines 140 to 142 in 060c5ca

   	latHtEEqn :: Relation
   	latHtEEqn = apply1 latent_heat time $=
   	defint (eqSymb tau) 0 (sy time) (deriv (apply1 latent_heat tau) tau)

@szymczdm The problems right now is that these 1) either need to be added to the equation section of the table, which doesn't have a place for any comments (i.e they are formed using only the Expr type). 2) Or the description section which is automatically generated based upon the variables in the equation section.

[szymczdm]

Alright, so 1, 2, and 3 all seem to be looking at supplementary (necessary!) information. These are non-trivial things we need to include.

Number 4 should be pretty straightforward, we just need to add a constraint to the phi chunk (wherever that's defined). We should already have the means to do this.

For number 5, that might be a new type of information (initial values) that we'll need to capture. But I'll need to take a second look to see if we have a mechanism for that buried somewhere already or not.

[balacij]

Looking at this again, I believe @smiths' original suggestion is possible. While descriptions are partially generated, they are generated from something. My first reaction is that $q_C$ should have "over area $A_C$" in its description. Alternatively, we can add a note in the description box that this definition only applies for a specific area. If we really want this to occur somewhere in the equation box, I don't think it should appear as text, but rather as a mathematical constraint placed on it. That being said, I'm unfamiliar with this project, so take what I say with a grain of salt.

[smiths]

@balacij there are two important pieces of information, the equation for $q_c$ and the boundary over which this equation applies. To reuse $q_c$ we want to easily be able to change where it applies. We want the text to appear, but what would be really great is if we could capture the "meaning" first and generate the text second.

When we have a partial differential equation in space (like the conservation of energy equation) to get a unique solution to the equation we need to specify the boundary conditions at the "edges" of the space. If we specify the temperature at the boundary we have a Dirichlet boundary condition. If we specify the flux (gradient) we have a Neumann boundary condition. The current case being discussed is a Neumann boundary condition.

We've never taught Drasil anything about partial differential equations (PDEs), but hopefully there will come a day when we can teach it the theory of PDEs.