aschaap / cas741 Goto Github PK

related to the previous issue, but in a different place; since there are no units involved in the problem of solving ODEs (as far as I understand), I have no use for the heading that announces a table of units. I saw Paul (@aoananp) addressed this by saying it is not applicable. Would you prefer this because it signifies that some thought has been put into it rather than potentially having been omitted?

The current state of the document is reflected here: https://github.com/aschaap/cas741/blob/master/Doc/SRS/CA.pdf

Thank you!

Is the equation field intentionally blank? How is this different from other tables where N/A is written?

@smiths
Hello Dr. Smith,

I've committed and pushed the first draft of my problem statement. I've included the PDF. Please let me know if anything needs to be improved.

Comments are available in a40b9b7.

I am not sure what OCaml and MetaOCaml are. You need to have them in the symbol table

You need to have a more clear and detailed description about the software such as what is the input and the output.

What is a Runge-Kutta method? How is it better than other methods/what kind of IVP is it good at solving? A quick, high-level explanation of this would be helpful (i.e. I really don't know how Runge-Kutta works, so can you bring me up to speed please? Assume that I know ODEs and IVPs).

You do not really have an MG, or an MIS; therefore, please change the name of the associated files in your repo. My suggestion is to have one file in the design folder named Design.tex. You can summarize your entire design deliverable in this file.

Alex,

I really like the way you presented your MIS.
Due to the fact that the format is a departure from the standard MIS format that was presented in class and the way your software is structured, it makes sense to write it this way.
I can't find anything else to comment on as it is an unusual write-up.

I do have one comment - I perused the document and I saw the "local functions" generated.
I'm not sure if I understood it correctly, but does it mean that the software will only have one exposed access program to the user called "odesolve"?
And that the local functions are the ones generated by it?
You could've provided a high level description and expectations of each local function created as part of the MIS - maybe their behaviour as well to provide some sort of guidance to the reviewer and maintainer of the code.

Otherwise, the document looks good. Dr. Smith has made some good comments.

There is also a typo you can look into with the Section showing as ??:

Cheers,
Paul

Since there is only one model in here, can you tailor the section introduction for this? I think it would read better.

"Numerical methods" is another definition I think that you should add to your list.

I think the non testing based verification need to be more specified. If you are going to have that you need to mention the methods(code review, code inspection...) and the corresponding tools and plans.

If you don't decompose your project into modules, I don't think you have to use the MG templete at all. Because there are too many things that do not make sense in your document like the introduction section, module decomposition section and etc. I have no ideas how to fit this to MG.

Since all of the testings are unit testing with OUnit. I think you need to have more detail and more former descriptions on section 6 instead of the plain text. For example you need to include the steps, input and output.

Please review the comments in the version of your CA that I pushed in commit number e4e9612.

I think you should lift the input requirements (initial value, interval, etc.) out of your goal statement and into the "Given the non-stiff ODE" part of this section (i.e. list all of the inputs in the same spot).

Additionally: What is a "spline"? "Type-safe"? These should be added to your definitions section.

I would ask Dr. Smith about this one first:

Shouldn't the equations be written such that the symbol being defined is the LHS and the equation that it can be found with is the RHS?

A trivial example: instead of writing x(t0) = x0 for Initial values (x0), write x0 = x(t0).

This is a minor issue, but the preamble to the Table of Symbols states that the symbols were selected to represent heat transfer literature and solar water heating systems. This should be updated to reflect Runge-Kutta instead.

Another small side issue - I don't know how Dr. Smith feels about this (I would check with him before making this change), but if your document reflects unitless models, I don't think that your table needs to have a column for units.

Hello Dr. Smith,

For solving ODE's, there aren't really any units to be used for the inputs. I've taken the liberty of replacing "SI Units" with "Units" (which was previously commented out) to denote that inputs belonged to e.g. real or complex number sets. I could change that to "Types" if preferred. What are your thoughts on this change?

The current document can be viewed at: https://github.com/aschaap/cas741/blob/master/Doc/SRS/CA.pdf

Thank you!

As presented, there is very little useful information in this section. The purpose has been stated, but the question of why this document exists is unclear (is it for maintenance? Is it the user guide?).

There is also no mention of who the intended audience of this document is. Is it for the person using the software? For someone who wants to expand or refine it? These are the same people that you describe in the User Characteristics section, but you need to be explicit about who they are and why they are using your software.

I already touched on this in Issue #21 (Assumptions) - isn't there some property of a correct solution that you could include here? Are there bounds that can be checked? Any kind of post-processing code inspection that can be automated?

If I understand correctly, this software already exists and the documentation is being written retroactively. While the software was being built, was there a specific reason why OCaml was chosen for the implementation language? If there is not, I think that this is a design decision and belongs in a future document.

As with issues #9 (User Characteristics) and (again) some of Issue #7 (Purpose of the Document), can you be more specific about the type of expected knowledge that the intended users need? What should the "other programs" support? What kind of knowledge do the programmers need to write these other programs?

I am not sure whether my understanding to your doc is on the right track. During compiling time, your program do not have information to determine any arguments of the generated function. Only after you giving all the information the program needed to infer the parameter type, parameter number, return type or other arguments, all information is going to be binded during run-time.This part I can basically understande.

But this process is taken care by machine. Modules are the things to show how you are going to code your program. For example, you may want to have a module to determine or infer how many parameters should be generated in the generated function. Although during compile time, you can not determine. But during runtime, machine can follow your code to infer these parameters. So I think modules are things used to introduce your code and help you organize your code.

I don't think Multi-stage Program has conflictions with having modules.

I am sorry that my knowledge to this is still limited. Probably, I just misunderstood something?

You should also clarify in your scope section of the SRS that your step size(h) is uniform for the entire computation.

Can you rewrite the definition of step size so that is does not explicitly refer to RK methods and exchange it for a more robust definition (e.g. the distance between points in what? For what?)? I think this can be made much clearer.

I added a few comments to your MG file in commit c0eb23b. As we discussed previously, I will not grade the document at this point. I will grade the design document that is committed when the MIS is due.

I don't know if the template was correct in the exclusion of the requirements or likely changes sections. Double check with Dr. Smith?

Could you alphabetize the list please? It would make it easier to look up terms.

Hi Dr. Smith,

It just occurred to me that one could interpret the Calculation heading to contain variabilities in terms of calculations performed between different family members. In my case, RK2 vs RK4 would seem different enough. Would this be abusing the Calculation heading?

Thank you in advance!

As it is written, the listing of subsections does not follow how they actually appear (i.e. you state that the instance models are followed by assumptions, etc., but assumptions come first in the document.).

In your case, aren't your Instance Models the same as your Calculations? You use both in this preamble and treat them as separate sections.

I think RK stands for something( Runge–Kutta?). It should be defined on the symbol table

Comments on the test plan are available in commit 4ab248a

What does "top down" mean for this document? What is included on each level (Can you be more specific about what these added details are as one proceeds through the document?)?

This description of the user is pretty vague. What kind of calculus? Programming courses (just functional)? The group of people with some understanding of undergraduate STEM is very broad...is someone from chemistry an intended reader?

Some of this ties into Issue #7 (Purpose of the Document).

I have a few questions here:

• For the order of RK, is the assumption that only second and fourth order methods will be used? Stating that "the user will specify..." sounds more like an input requirement and belongs elsewhere (e.g. an input specification or a user responsibility).
• Stating that your ODEs must be stiff and continuous belongs here rather than stating it in your Goals section (i.e. remove it from your goal section so that it has a broader starting scope and narrow it with your assumptions)
• Isn't stating that the output of the vector of an ODE must match the size of the input vector part of the correct solution specification (Output subsection)?

Some more smaller points to deal with:

• You introduce some new notations here (k, Y) that should be added to your Table of Symbols.
• This could be my unfamiliarity with RK methods, but doesn't second order come before fourth order? Can you swap the table order to reflect this please?
• Most of the side notes you have in brackets () could be incorporated into the body text with some rewriting, and I think it would help with readability.

Going by your suggestions and example from class about a word processor being a family of programs due to turning off spell-checking yielding a new member of this family, I assumed that generating different code for every ODE would count as a program family. However, it seems Dr. Carette disagrees, due to metaprogramming introducing the only variability. Did I misunderstand or not understand completely?

Thank you!

Can you be more explicit about the interface dependencies between your system and external ones? From what I can see, there is a dependency between the parent program/user and the generator, and the parent program/user and the generated code. Does this mean that the parent program/user does not directly interact with the generator to get its outputs? It can just pick it up from somewhere else (the generator does not send it back to the calling program/the calling program does not request it from the generator)?

A much smaller issue - can you write some sort of lead in for the responsibility lists (an "in general" description of what the user and program responsibilities are)? Right now, they just appear with no warning as if they were added as an afterthought.

You state that user's will have to "process the output appropriately". What is the final output of your program? Is your software a code generator (produces programs) or does it simply solve an ODE (outputs values and functions)? This hasn't been stated yet, so some of the context is missing.