The project license should be permissive considering the use of the library in the industry.

Add the test files for each shaft_element.py, disk_element.py and bearing_seal_element.py

Create objects, attributes, methods and UML diagram.

This change was supposed to be in the last pull request regarding the fluid flow code. We noticed today it wasn't there. Instead of providing the position of the rotor center, the user will provide the eccentricity, which is the distance between the center of the rotor and the stator.

I've been trying to access the bearings' stiffness coefficients ('kyy') from this pandas dataframe shown below.

df_bearings = pd.DataFrame([el.summary() for el in self.bearing_seal_elements])

I'm using this code line
self.df_bearings.loc[i, 'kyy']

but it returns its memory address instead of its value
<bearing_seal_element._Stiffness_Coefficient object at 0x000002330DC8F128>

How could I get the "kyy" value from the dataframe then?

We need to add book examples to fluid flow code to the code instead of the entry data we have now. We also need to verify if the results are according to expected.
Here what needs to be done to close this issue:

[edited on April 7, 2019]:
Short bearings:

• Add analytical expression to the code;
• Add tests to integrate with pytest;
• Add a working example from a book with results matching with ours (book must be referenced).

Long bearings:

• Add analytical expression to the code;
• Add a working example from a book with results matching with ours (book must be referenced);
• Add tests to integrate with pytest.

Middle size bearings:

• Add numerical calculus to the code;
• Add the real data we have;
• Add tests to integrate with pytest (the real data and our results must match).

Tests are missing for the material class. We need to implement the tests using pytest.

This is a good talk about testing:
Andrew Knight | Testing is Fun in Python!

A more in-depth tutorial:
Michael Tom-Wing, Christie Wilson - Introduction to Unit Testing in Python with Pytest - PyCon 2016

Now we have created elements and some materials, we could start implementing files to generate some analysis of the rotor. What do you think?

This was a suggestion made by @thiagoritto, so that newcomers to the project (or online collaborators) can know straight away which applications they should install and what they do.

Tests progress:

• Static analysis tests

• Convergence analysis tests

The website for documentation currently is based on the /docs folder of the ross repository.
I have noticed that this can bring us some problems:

• The generated website is based on files present on the /docs folder, but when the files are generated by sphinx they are placed on the _build directory, and we have to copy them which is error-prone;
• Mixing source files and generated files makes the repository cluttered;
• Generated files such as .html and .css can mess up the GitHub statistics, resulting for example in a massive amount of lines of code and error on the language percentage for the repository.

I believe a better approach is to have a separated repository for the website, this way we can set a gh-pages for that and the ross repository would only have the source files for the documentation.

TODOs:

• Create, inside the ross organization, an additional repository for the website;
• Clean ross repository leaving only documentation source files.

Taking the following code as an example:

import ross as rs

steel = rs.materials.steel
n_el = 10

shaft = [
    rs.ShaftElement(1.2/(n_el), i_d=0.03, o_d=0.08, material=steel,
                    shear_effects=False, rotary_inertia=False)
    for i in range(n_el)
]

disks = [
    rs.DiskElement.from_geometry(n=(n_el / 2), material=steel,
                                 width=0.08, i_d=0.08, o_d=0.4)
]

bearings = [
    rs.BearingElement(0, kxx=1e15, cxx=0),
    rs.BearingElement(n_el, kxx=1e15, cxx=0)
]

When calling the plot function the bokeh figure is like this:

Which is not correct since the example has a hollow shaft - i_d=0.03

See the matplotlib plot as reference:

I think we should take Friswell examples and exercises and reproduce them with ross.
These notebooks can be added as part of the documentation.

• Example 5.8.1
• Example 5.8.2
• Example 5.9.1
• Example 5.9.2
• Example 5.9.4
• Example 5.9.5
• Example 5.9.6
• Example 5.9.7
• Example 5.9.8
• Example 5.9.9
• Example 5.9.10
• Example 6.2.1
• Example 6.2.2
• Example 6.2.3
• Example 6.3.1
• Example 6.3.2

Considering the following code:

import ross as rs

steel = rs.materials.steel
n_el = 10

shaft = [
    rs.ShaftElement(1.2/(n_el), i_d=0.03, o_d=0.08, material=steel,
                    shear_effects=False, rotary_inertia=False)
    for i in range(n_el)
]

disks = [
    rs.DiskElement.from_geometry(n=(n_el / 2), material=steel,
                                 width=0.08, i_d=0.08, o_d=0.4)
]

bearings = [
    rs.BearingElement(0, kxx=1e15, cxx=0),
    rs.BearingElement(n_el, kxx=1e15, cxx=0)
]

If we try to check steel, disk and bearing __repr__ we get:

>>> steel
Steel
>>> disks[0]
<ross.disk_element.DiskElement at 0x7f7b66af7e80>
>>> bearings[0]
BearingElement

We should implement better __repr__() methods for these objects (especially disk).

According to the python docs:

If at all possible, this should look like a valid Python expression that could be used to recreate an object with the same value (given an appropriate environment). If this is not possible, a string of the form <...some useful description...> should be returned.

A simple example of this is:

class Car:
    def __init__(self, color, mileage):
        self.color = color
        self.mileage = mileage

    def __repr__(self):
       return (f'{self.__class__.__name__}('
               f'{self.color!r}, {self.mileage!r})')

• Material repr() method
• DiskElement repr() method
• BearingElement repr() method

We decided to create a fluid flow routine that can be calculated analytically before the numerical one.

Create element files for shaft, disks and bearings.

Implement a material class considering a .json file that will hold the names and properties for each shaft material.

Since we've already started working on tests to generate some results, I thought it would be useful to introduce a pre-processing test. It's a convergence analysis. It refines the shaft elements mesh and checks the relative error between the eigenvalues (self.evalues) and the undamped natural frequency (self.wn) calculated in each step of refinement, and it stops when the relative error reaches a particular value.

Add the test file to check the correct work of rotor_assembly.py file.

Write a contribution guide, detailing cloning, commit, pull requests etc.
Take as an example https://docs.scipy.org/doc/numpy/dev/

Verify which one is more readable and use it as standard.

The examples for the docstring also need to be tested. The example for rs.Rotor class was not working due to modifications such as the addition of the .from_geometry() and .run() methods.
We need to implement automated tests (preferably integrated with our CI).
pytest is capable of running this kind of tests (see here).

• Automate doctests
• Add to doctests appveyor
• Add doctests to travis CI

Some arrays and formulas have been modified because of black. For arrays and formulas that need to be compared with references such as books, we should use the # fmt: off option available on black.
I will check our code history and see where this is applicable and modify the # fmt: off line accordingly.

Implement simple hydrodynamic journal bearing as described on Friswell's book considering:

• the flow is laminar and Reynolds’s equation applies
• the bearing is very short, so that L/D << 1, where L is the bearing length and D is the bearing diameter, which means that the pressure gradients are much larger in the axial than in the circumferential direction
• the lubricant pressure is zero at the edges of the bearing
• the bearing is operating under steady running conditions
• the lubricant properties do not vary substantially throughout the oil film
• the shaft does not tilt in the bearing

Generate a report with the main results from the rotordynamic analysis.
Some criteria should be used to state if the report is ok according to a standard.

The class BearingElement must allow inputs from excel type files. A separated routine should be included to convert from excel to csv and then from csv to toml.

instantiated rotors could be saved for future use.

Saving elements (shaft, disk, bearing and seal) in different files. Each element class should have your own save file.

Other options are:

• saving the rotor assembly's matrices

• saving arrays from results to retrieve graphs.

• Autorun a method when the user opens a saved file showing the rotor model.

Add CI that uses windows. Verify if travis does this, if not, appveyor could be an option.

As discussed on #79, the n argument is not explained in the BearingElement class.

• Explain that n is the node in which the bearing will be located
• Add example of use to the docstring

Appveyor is performing the builds when we have a PR as we can see it here.
The problem is that when we have a PR we only have 1 check performed:

which is the check from travis ci.
So, if we the appveyor build fails, github won't block the PR.

We need to develop a way to profile our code, measuring the time spent at each step of our calculations.
This can be done using cProfile and snakeviz for visualization.

The profile report will show something like the following (taken from the snakeviz page):

The table contains one row per unique function called. Calls to the same function from different places are all grouped into one row. The columns are the same as described in the cProfile user’s manual:

• ncalls: Total number of calls to the function. If there are two numbers, that means the function recursed and the first is the total number of calls and the second is the number of primitive (non-recursive) calls.
• tottime: Total time spent in the function, not including time spent in calls to sub-functions
• percall: tottime divided by ncalls
• cumtime: Cumulative time spent in this function and all sub-functions
• percall: cumtime divided by ncalls
• filename:lineno(function): File name and line number were the function is defined, and the function’s name

With this report we will be able to:

• Know which functions are slow and need optimization;
• Check the impact of an optimization and see if it is worth doing it (considering that some optimizations can make the code less readable and be harder to maintain);
• Check if some new feature is making our code slow;
• Have benchmarks for each realease.

Currently, the calculation of some rotor parameters such as eigenvalues, damping rations etc. is done automatically when the speed (w) is changed. This calculation not carried out in an explicit manner, meaning that the user is not aware that these parameters are being recalculated when the speed is modified.
Maybe a better approach would be to implement a run() method that would have to be explicitly called by the user to update the rotor state.

Fluid flow is currently being plotted using matplotlib. We should change to bokeh library. However, fluid flow is still a branch and we still haven't fixed some of its issues, such as adding an example from literature and make sure results are matching. We should focus on solving previous issues regarding fluid flow before focusing on this issue.

We should set a CI to automatically build and test the code pushed to the repository before merging on master.
I think we should use Travis CI since it is free for open source projects and it is easy to use.

Create a tutorial with a jupyter notebook to explain the library basic objects and functionality.
This notebook can be rendered by sphinx and used in the documentation.

There are some divergences in some examples such as anisotropic bearings and damped bearings.

Fluid_flow.py was added in a new branch called "fluid-flow".
Here are some changes that should be made in it.

• Translate comments, names of variables and functions.

• Add docstring to explain functions.

• check PEP 8

• Remove TODO from the code and add them here

We should add a binder / colab with the examples notebooks as part of the documentation.
These services provide live notebooks in an executable environment so that the person reading the documentation can execute the examples.

Implement documentation using sphinx.

Use coverage to check the tests.

We will need to add the package to the pypi (python package index) to enable installation of the package with pip through the command:
$ pip install <package name>

The name ross is already taken on pypi, so we will need to think about an alternative.

The class Element is repeated on different files: shaft_element.py, disk_element.py...
I think we should have that class in a separate element.py file and the other modules should import from it.

As explained here

Branch protection is part of a powerful set of configuration options that give repository administrators the ability to enforce security policies by preventing accidental branch deletions, enforcing code reviews, and requiring successful automated checks before pull requests can be merged.

The documentation page generated by sphinx is not showing on https://ross-rotordynamics.github.io/ross/.
For some reason the README.md is displayed on the page instead of the html generated when running sphinx.

Add a method to calculate static displacement.

Currently, the rotor is plotted using matplotlib, but it would be nice to have a plot using the bokeh library .
With this library, we can create interactive plots for web browsers. It would be nice to have a hover tool to show the properties of each rotor part.
@rodrigomoliveira1 @flaviorangel @GabrielBachmann can one of you guys take a look on this?

The rotor radius is being calculated arbitrarily. The user must be able to choose which structure they want for the rotor radius. This choice should be done when the object is instantiated in the form of a parameter the user will give, if they so wish.

In the #8 PR I have noticed that there was a ^M character at the end of some lines:

It looks like this breaks the diff for the file.

One important aspect for facilitating read and review of the code is to have a standard code format.
A good python library to do this is called black.
This library is easy to use and can be used together with git and editors such as pycharm.
I will be updating the current code base with this library and will also add a file so that black can be used together with git pre-commit.