What spaces/symbols/units do we actually use?

[smiths]

Create an inventory of the spaces, symbols and units we actually use. @JacquesCarette suggested in meeting #3496 that tools Jason has created can be used to spit out cases where they occur. The discussion was about spaces, but hopefully the automated reporting of symbols and units is also possible. The number of symbols will be large, so we definitely want automation for this one.

During the meeting we thought that all three could be done at once, but if it is helpful, this issue could be split into three issues. One for each of space, symbol and unit.

[janim2-2004]

Uses of Symbol

Label

Here are some typical use cases of Label:

A Label here is used to create a implicit variable

-- Case 1 - Here we use the 'lable' function which is the same as using 
-- 'Label' but throws and error if there are any empty arguments.
mthdArg = narg $ implVar "method_scipy" (nounPhrase
  "chosen method for solving ODE" "chosen methods for solving ODE")
  String (label "method")
-- Case 2 - here we use just Label
makeControlled = quantfunc $ implVar "make_controlled_odeint" (nounPhrase
  "function for adding error control to a stepper"
  "functions for adding error control to a stepper")
  (Actor "auto") (Label $ odeNameSpace ++ "make_controlled")

A Label here is used to create a Unit Chunk (UnitDefn)

calorie = derUC "calorie" 
  "calorie" "energy" (label "cal") (scale 4.184 joule)

A Label here is used to make a UnitalChunk

-- lbodyA and lBodyB are Symbols constructud using 'label'
-- rigidParam is a unital chunk constructor
massA      = rigidParam "A" lBodyA
massB      = rigidParam "B" lBodyB

Variable

Here are Some Typical Use Cases of Variable:

the file ShortHand.hs contains all of the upper and lower case English letters along with many Greek letters and symbols.

cA = variable "A"
cB = variable "B"
cC = variable "C"

It is also used to create some Symbols within the examples. (Most of these should be changed to use the Symbols created in ShortHand.hs)

syminvLaplace    = variable "L⁻¹[F(s)]" -- Split into its components?
syms             = variable "s"
symFt            = sub (variable "f") $ label "t" -- What is the motivation to use a label instead of variable.

We should also consider pre defining brackets as symbols, as we use them very frequently, eg.

linearAccel            = uc CP.linAccel               (Concat [lA, label "(", lT, label ")"])     Real        accelU
linearDisplacement     = uc CP.linDisp                (Concat [lU, label "(", lT, label ")"])     Real        metre
linearVelocity         = uc CP.linVelo                (Concat [lV, label "(", lT, label ")"])     Real        velU

[JacquesCarette]

The above "Uses of Symbol" for Label doesn't make sense to me. I think there is a lot of implicit information in your head about this investigation that you have not written down in the above comment - but that information is crucial for others to understand what you mean.

[janim2-2004]

Integ (Symbol)

There are very few uses of Integ, all of which are withing the examples, this could be moved a higher level file as they are reused often.

label0  = Integ 0 -- Calling it label0 implies that it is a label
label1  = Integ 1
label2  = Integ 2

[janim2-2004]

Special (Symbol)

This is only used to represent the degree symbol, although the comment in the code also mentions the use for partial derivatives.

degree = fund' "degree" "angle" (Special Circle)

centigrade = derUC "centigrade" 
  "centigrade" "temperature" (Concat [Special Circle, label "C"])
  (shift 273.15 kelvin)

[janim2-2004]

Atop (Symbol)

Hat

The unit vectors are most of the uses for hat.

uNormalVect = dqdNoUnit CM.normalV  (vec $ hat lN) Real
unitVect    = dqdNoUnit CM.unitV    (vec $ hat lI) Real
unitVectj   = dqdNoUnit CM.unitV    (vec $ hat lJ) Real

There are some other uses within the examples like

dimlessLoad = vc "dimlessLoad" (nounPhraseSP "dimensionless load") (hat lQ) Real

Vec

This is the most common use of Atop, just simply used to make vectors.

torque                 = uc CP.torque                 (vec lTau)                                  Real        torqueU
velocity               = uc CP.velocity               (Concat [vec lV, label "(", lT, label ")"]) Real        velU

All uses are similar to this, located in Math, Physics and the Example files.

Prime

This is only used in the ssp example

effectiveStress = uc' "sigma'" (cn' "effective stress")
  (S $ "the stress in a soil mass that is effective in causing volume changes " ++
   "and mobilizes the shear strength arising from friction; represents the " ++
   "average stress carried by the soil skeleton")
  (prime lSigma) Real pascal

effNormStress = uc' "sigmaN'" (cn' "effective normal stress")
  (S $ "the normal stress in a soil mass that is effective in causing volume " ++
   "changes; represents the average normal stress carried by the soil skeleton")
  (prime $ sub lSigma cN) Real pascal

[JacquesCarette]

You're looking at this at much too low a level. We don't need to know the kinds of symbols that are created, but for what purpose, and when are things "weird".

Examples of weird:

1. putting in explicit parentheses (like velocity above) in the name of something, especially when that something is not of a function type
2. putting in a hat or a vec on something that is not of type Vector

For purpose, one of them is clear: as a "symbol" to display when a variable (representing some kind of quantity) is displayed. The question is, is there any other purpose?