smiths / vdisp Goto Github PK
View Code? Open in Web Editor NEWSoftware for 1D Settlement Analysis
Software for 1D Settlement Analysis
Following from #7, the next step is to setup a very simple GitHub action. I would like to get the infrastructure for this setup early.
Please do the following:
src
folder in the new branchmain
The Julia module isn't intended to be something we use in the long run. It is just a simple thing we can do to set up the infrastructure. This is us "bootstrapping" our infrastructure. Once we get it so that this works, we will try to have it so that main
always passes our continuous integration tests.
The CI approach of testing as we go along is working well. However, over time we are going to lose track of the traceability between test cases and the modules. There are test cases from 5 different test files, but the test file names don't provide any clue as to what they are testing. The output while running the tests is also uninformative.
Is there a way to test where the traceability to the modules is more obvious? For instance, can we have separate testing files, with each file containing the unit tests for a corresponding module?
I don't know what the Julia way of doing this is, but as the project grows we are going to want to be able to maintain the test cases. In the Verification and Validation plan we can make tables to show what test files and which test cases are testing which modules, but it would also help if the code was self documenting.
@EmilSoleymani, given that you are learning about Julia installation and usage, this would be a good time for you to write up what you have learned for future users. Let's create a "Getting Started" Wiki page. You can use the "Getting Started" page from the Drasil project as a starting point.
I haven't installed Julia yet, so I can test your instructions by following them.
It is never too early to start thinking about system tests. These are the tests that we will use when the new software is complete. Unlike unit tests, which test small subsets of the code, system tests test the entire software system. One obvious system test is the original test that Dr. Stolle gave us with the original FORTRAN code. We want to think of other tests along those lines. We should be looking for system tests that test the different options provided by the software. To record the system tests start a document, preferably in LaTeX, that lists the tests. You should characterize each test with a natural language description and then link to an input file that will provide that test case. Since we have the original FORTRAN software, we can also link to an output file.
@EmilSoleymani, as we discussed at the end of our last meeting, please add theories to the SRS document. Please use the \deftheory
command, so that we can easily change the formatting. You can add the theories that you know from your work on explaining the code. Some theories that you can borrow from the ssp example are:
If it helps, the generated LaTeX code for the SRS SSP is available here
Also, please try to add Saint-Venant's Principle as a theory.
Compile and run the FORTRAN CODE.
@EmilSoleymani as you finish going through the FORTRAN code we should start planning your implementation. To discuss the design, I would like you to write a module guide. To write your module guide you can look at these resources:
You can consider using my template module guide. You don't need to fill in all of the sections though. Your goal, to begin with, is to identify your proposed modules and the secrets and services for each module.
To understand your design, we'll also need a preliminary Module Interface Specification (MIS). I'll create another issue (#29) about that.
Deduce purpose of BLOCK DATA
in FORTRAN code lines 377-397. More info here in issue #14.
I decided to begin with the coding as discussed. I wanted to first tackle the problem of parsing the input file VDIN.DAT
using Julia. This has been quite easy so far, I am about halfway done.
I have found out how to get the textbook version of calculations to correspond to the calculations done in the code. I have successfully recalculated the same test cases as yesterday, this time using the original formula from the textbook. I should soon make a pdf of my handwritten calculations, and also add a dostring for the getSurchargePressure
function.
@EmilSoleymani, the CI system doesn't seem to be updating the documentation. Do we need to do something to get it updated?
I wonder if we should split InputParser.jl into two modules. One to read the input from a file and another class that creates instances of InputData. The struct where you define the input data is encapsulated with reading the file, but we might get our input data from another source. (This is why I like to talk about likely changes.) ๐ We could have a graphical interface that gives us a new instance of InputData. We could also have a program that changes InputData systematically. Maybe we modify the size of the footings as part of an optimization algorithm? It would be good to be able to do this.
Find equations/theory for SLAB
subroutine in lines 218-266 of the FORTRAN code. More info here in issue #14.
Find equations/theory for COLL
subroutine in FORTRAN code. More info here in issue #14.
The variable GAW, supposedly representing gamma_w, is said to be the unit weight of water. This constant is known to be 9.81kN/m^3 in SI Units. The book clearly states that it is 0.031tsf. Tsf is tonnes per square foot, and does not translate to N/m^3. In fact it is a unit of pressure, and translates to N/m^2 in SI Units. Find an explanation for this discrepancy in unit conversions.
To create new code, we need to figure out what the old code does. We should go through the FORTRAN CODE and say what each "chunk" of code does. I think we can use the features of GitHub to make this relatively easy to do. For instance, we can do something like:
Code to initialize program, declare variables for PP, G and WC, and open files:
Lines 1 to 9 in 0ee7174
We should probably also keep a dictionary of variable names and their meaning. For instance, I don't know what PP, G and WC are. ๐ I feel like the W means water. G might be specific gravity? We'll figure it out.
In the material properties screen:
Some languages have "prettiers" that go through the code and make it conform to the required formatting guidelines. Please search to see if Julia has prettiers that we can use. (The prettier can potentially be part of the CI process.)
Understand SPLINE
subroutine in FORTRAN code. More info here in issue #14.
As requested in #60 add test cases to assert if the proper error is thrown in InputParser.jl
In the final stages of entering data (EnterDataStage4, EnterDataStage5, EnterDataStage6), there is a button to Select Output File
. Once selected, we should display the name of the selected file.
Eventually we want to document our requirements in a Software Requirements Specification. The template we used is based on my template, as given in SmithAndLai2005 and SmithEtAl2007. (The papers and their bib
entries are in the pub repo.)
Sample SRS documents can be found in:
I have made some changes to the SRS template recently. The new version more explicitly discusses the refinement of theories. You can find a preliminary example for NoPCM.
Currently relying on returning -1 in parseCurrentLine
function, learn proper exception throwing/handling and implement it. Also learn how to deal with Type errors when parsing (i.e. if we try to parse "a" as an Int) and implement it accordingly. Related to #40.
When I try to pass Julia functions to QML, a very important part of the process, I get an error that says "Could not find module QML when looking up function get_julia_call". This was not present in my Julia Thermostat example. A quick google search lead me to this open issue which explains the problem. It seems to be related to module QML being present in the same directory. Since our vdisp.jl
is in the vdisp/src/
folder, and our Project.toml
is in vdisp/
, the QML.jl
module is not being found when I call the @qmlfunction
macro.
As I mentioned in the MG pull request, I think you are on to something with the UML diagram. I think we may still document the design in the MG document, but for discussing the design, the graphical nature of the UML diagram and design patterns are better than a LaTeX document.
I'd like you to update your UML diagram, if you can, to remove the heavy use of strings in the interfaces. I understand why you did that, but strings are an opaque data structure. We only have the string. We lose what it means.
I believe the problem is that the different options (NOPT?) lead to different outputs. What if we have an interface that has behaviours that are the union of all possibilities? In some cases the implementation of the behaviour will be uninteresting, or maybe even an error to request. The good thing is that every option would then have the same behaviours.
If you have read the Head First Design Patterns book, you see an example like this with the Duck example at the start. For instance, the ducks all have a quack method. However, the wooden decoy ducks implement quack as silence. I have a feeling we could do something analogous.
If you haven't seen the Head First design patterns book, I think I might have an electronic copy somewhere that I could look for.
Extensions: LaTeX Workshop
LTeX - enable picky rules when you are confident in a document
consider increasing "Sentence Cache Size"?
Please create separate issues for each of the unresolved questions on the original FORTRAN code, as discussed in #14.
So that we can refer to the current view of the UML design document, please put it in the MG folder. A picture of your hand-drawn design is fine for now, but at some point we should update to an electronic drawing, like that which can be generated via draw.io.
Related to #8, our build is failing for the documenter. Any guesses on why? I did have my secret in the wrong spot before, but I've fixed that. It doesn't complain about the environment key anymore, but it is failing for a new reason.
https://github.com/smiths/vdisp/actions/runs/2270910534
@EmilSoleymani, if you don't have any explanation, I can ask Jason for some ideas.
The examples where the code and the documentation have errors and or inconsistencies are valuable for future papers. @EmilSoleymani we should keep track of them as you discover them.
Please create a file where you put all of the examples where you find mistakes/inconsistencies in the code and documentation. In some cases we might later find that the misunderstanding is ours, but it is best to have these in one place to consult. We can also ask Dr. Stolle to review our examples. You've already fixed one typo in the code. In issue #14 you mention potential issues with the textbook.
You can create the file in whatever file type is most convenient for you. A wiki entry or as a LaTeX file, would be fine.
Add a Makefile in test directory with make test
rule. Should activate Julia environment, install Test package, and run tests.
Related to comment from PR #45.
Understand SOLV
subroutine in FORTRAN code. More info here in issue #14.
To understand the design we want to divide the system into modules (documented in the module guide #28) and we want to sketch out the interface for each module.
I have a template MIS, but I think this is too much work to begin with. All we need for each module is the following:
We can follow the MIS Format I used in SE 2AA4.
Examples can be found in the SE 2AA4 notes for A2 and A3 each year. For instance, the chemistry example.
Another examples is the MIS for the solar water heating system and for the slope stability analysis program.
Follow the example in the family of material models document.
We will either use Python or Julia for our implementation. Please create a list of pros and cons of each option so that we can settle on a choice.
Currently, in EnterDataStage1.qml
, the foundation diagram is displayed with an orthographic projection. Change to normal view.
The list of likely changes (anticipated changes) in the MG is a good start, but we should work to brainstorm more. We want to think of everything that we might want to change in the future. We won't necessarily design to satisfy all likely changes, but it is better to discuss it before the design gets too set. We can brainstorm the likely changes here, and then when we are done, you can add them to the MG document.
I don't just mean likely changes that you will do this summer. Any changes that might be desired by a future developer are also candidates.
As a start, here are some potential likely changes that come to my mind:
Please add to the list @EmilSoleymani. Any ideas of things that you think would be neat changes are welcome. We are brainstorming, so there are no bad ideas. ๐
@dstolle
While trying to evaluate the Schmertmann Model through hand calculations, I had trouble finding the formulas for I_iz
in the textbook. Here are my hand calculations:
The formulas for I_iz I have put in this document are from the code. I couldn't find them in the book. I was wondering if you had any resources that mention this formula.
Figure 3-4 on p.33 suggests, this formula might be in the following publication: Vol 104, 1978, "Improved Strain Influence Factor diagram", by J. M. Schmertmann, J. P. Hartman, and P. R. Brown, p 1134, however, I cannot find this document online.
@EmilSoleymani I have some initial thoughts on the UI design that I will record below. I really like you mocking up the interface before implementation. This really helps with visualization. My comments are ideas. If you disagree, we can discuss. If you agree, then we can turn the comments into issues. @dstolle, if you have any comments on the UI design, feel free to share them as comments in this issue, or in a separate issue, or over e-mail.
It would be nice if we could find an application that has a nice interface that we can model our interface after. For adding new rows I thought of the activities report that the faculty asks professors to fill in each year, but it isn't a public app, so I can't send you to it. I'm sure there are other examples, but I can't think of them right now. @dstolle, if you can think of an app that has a nice interface, let us know. ๐
We should do user testing once we have a working prototype. It would be great to get user feedback. I'm sure we could find some undergrad or grad students on campus that would test the program for us.
The link you found to the Settlement Analysis book is a great find. Please add a link to the book in our README file. We'll eventually do a better job of organizing this information. For now, it is enough to put related information in the same file.
We should look to see if there is a linter for Julia like flake8
for Python. Linters can be a great help in writing standardized code that avoids common pitfalls. If such a tool exists, we could work it into our CI script.
I think we should remove this branch from the github actions instructions:
@EmilSoleymani please review the geotechnical engineering material prepared by Dr. Stolle. The following is related to the project:
I think you will find this easier to read than the settlement analysis book.
We should explain the purpose of the Project.toml file in our README file.
Along the lines of #11, let's create a Wiki page on getting started with Julia. Our goal is to have a project that can be actively maintained. This means that we are preparing for future developers. Given that we have adopted Julia, it would be good to have some information on Julia. We shouldn't teach Julia. The wiki page would be a list of recommended readings - urls that interested parties can consult. This also has the advantage of being useful for me and Dr. Stolle. ๐
Understand BICUBE
subroutine in FORTRAN code. More info here in issue #14.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.