-
Notifications
You must be signed in to change notification settings - Fork 4
Developer Notes
Here, we document best practices for developers and the inner workings of MachLine. Unfortunately, this will probably never be comprehensive. However, this, along with the code comments, should ease the learning curve for new developers.
At this point, we don't have any plans to implement community development. Development efforts will remain in-house for the time being. However, we do greatly appreciate the contributions of community members in testing the code and reporting bugs.
MachLine is:
- Object-oriented (using type-bound procedures)
- Well-commented
- Easily-extensible
- Modular
You can read more about type-bound procedures here. They take a minimal amount of extra effort and are the right way to do things.
Start with this video. It is a phenomenal, high-level introduction to Fortran programming.
Here is the series of videos made by Cory Goates to introduce members of the AeroLab to Fortran.
This webpage provides a pretty extensive list of Fortran tutorials.
For learning OpenMP, this YouTube playlist is extremely helpful.
- You can name
criticalblocks. This is very useful for some cases and highly recommended.
Git and Github are incredibly powerful tools for developing code, especially when multiple developers are involved. As such, they should be used properly. Please follow the following development guidelines when working on MachLine:
Branches in Git allow for efficiently separating and bringing together different thrust of development. MachLine has two branches, main and test that always exist. Other branches may be created and destroyed as needed.
The main branch is production code. Think of this as what we're putting on the shelves for customers. Any code that gets to main should be thoroughly tested, debugged, commented, and maintainable. Changes to main should be made relatively infrequently.
The test branch is the staging ground for main. test is where individual developers can merge and test their respective changes to the code before pushing to main. However, test should not be used for active development.
Teams of developers should be doing their work on new branches separate from both test and main. For example, those working on wake relaxation methods may create a branch called wake-dev to work on. Once they have finished their work, they can merge their branch with test.
When changes are made to main, increment the version number. This is gone in git by executing git tag v<VERSION NUMBER> and git push --tags. The version number should also be incremented in the ASCII logo in src/main.f90. Big changes mean an update to the first version number (i.e. v3.2 going to v4.0). Small changes mean an update to the second version number (i.e. v3.2 going to v3.3). Also make note of changes on the Version History page.
Regression tests have been included for your (the developer's) benefit (see Unit Tests). Run them often using py.test test/. If you have added a new feature, add a regression test. Keep the regression tests short and simple. The faster they are to run, the more likely future developers will be to run them.
Sometimes you will make changes to the code that intentionally break previous regression tests. Only update old regression tests after you have thoroughly tested the new code and are confident of the new results.
When merging, always merge into your branch first, and then update the other branch. For example, if I've been working on a new feature on the branch wake-dev and want to merge my new code into test, I would first (while on the wake-dev branch) execute git merge test. This merges test into the branch I am working on but leaves test as it was. I can then resolve any merge conflicts and test the code on my branch. Once I am confident that the merge worked and everything is running properly (this is where the regression tests come in), then I can commit the merge, checkout test, and execute git merge wake-dev to pull the changes made to wake-dev into test. I will then double-check everything again (regression tests) before pushing to the Github repository.
If a bug is found that needs to be fixed ASAP, create a new branch off of test or main to fix it (I include main here because there may be features on test not yet ready for release). Fix the bug, and then follow the above procedure for merging back into main. And delete the bug fix branch once you're done with it.
Keep the Wiki up to date. Bad documentation is what kills a code.
To maintain a consistent code format, follow these guidelines:
- Use indenting to highlight code blocks (i.e. do loops, if/else statements, etc.).
- Leave two blank lines between type, subroutine, and function definitions.
- Always use
implicit none. - For type-bound procedures, the naming should be:
procedure :: <PROCEDURE_NAME> => <TYPE_NAME>_<PROCEDURE_NAME>. For example, if I want to bind a functionget_areato thepaneltype, I should name that functionpanel_get_areawithin the module and bind it usingprocedure :: get_area => panel_get_area. - Module names should always end in
_mod. - Use underscores for separating words within variable and procedure names. Do not use camel case.
- Whitespace, whitespace, and more whitespace. Lines of code are free, so use them.
- Fortran doesn't care about character case, so just keep things lowercase unless you have a reason not to.
On each of the following pages, we've tried to make notes about each of the modules present in the MachLine source code. The source code is divided between the src/ and common/ directories. The idea is to keep code unique to MachLine in src/ and more generally-usable code in common/.
To truly understand some aspects of the source code (such as boundary conditions, influence calculations, etc.), it is best to have a thorough understanding of the theory of MachLine. This theory is presented in the sources listed on the Literature Page.
The src/ directory contains modules specific to MachLine that are not likely to find application elsewhere.
The common/ directory contains modules that are ignorant of the inner workings of MachLine. That is, they can be easily used in other projects.
The test branch is where all new features should be added, but the documentation reflects the main branch. Here is where we keep track of features added in test that will need to be added to the wiki as soon as test is merged into main.
- Control point offset types
- Subsonic off-body velocities
- 5 deg default MCA
- Neumann, doublet-only, least-squares, mass-flux BC (control point offset has no effect)
- Neumann, doublet-only, least-squares, velocity BC