smiths / caseStudies

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

SSP assumptions in code not captured in SRS #151

Closed bmaclach closed 5 years ago

bmaclach commented 5 years ago

While trying to wrap my head around the math in SSP, I noticed that there were some forces for which I did not understand how their values were obtained. Looking at GD1 as an example: image Kc (seismic coefficient) and Qi (external load) are part of this equation, but nowhere in the data definitions are there valid equations to obtain these values, nor are they listed as inputs to the system.

I resorted to looking at the implemented code in the src/ directory, and found that both of these values are hardcoded as 0 in the implementation.

My question, then, is whether I should add assumptions to the SRS stating that there is no seismic force and no external load, and adjust the resulting instance models accordingly, or if we want to update the code to no longer assume these values, and instead take these values as input parameters (and adjust the SRS with these new inputs).

smiths commented 5 years ago

Great catch @bmaclach. Your first option is the better one - add assumptions that move these forces out of scope, and then remove them from the documentation.