Suggestions for docs

[rafmudaf]

I read through the documentation for the first time, and it's really great. It flows nicely, and I was able to read straight from the beginning through the examples very easily. A few things stood out that might make the onboarding process a little more clear, and I've included those notes below.

• The load_config tutorial page says expected_config gives you a blank dictionary with the required units for each field. However, the project_manager page says the blank dictionary has the Python data type rather than the units. I'm not sure if this is intentional, but this difference stood out.
• It would be helpful to note the distinction between design and installation modules earlier. It's first stated in Design Modules but it's ambiguous prior to getting to that point. Considering expanding in the Overview section something like "ORBIT includes many different modules that can be used to model phases within the BOS process, split into design and installation where the outputs of design modules can optionally be used as inputs to the installation modules."
• Describe the concept of the "Library". This first came up in example 2 and it felt abrupt. Even after the examples, I don't have a sense for what the "Library" means to me (the user).
• I think the path for configs in the examples should be ~/examples/configs (see here)
• Consider adding installation instructions to the docs page
• The README says Python 3.9+ is supported, but <3.12 is required

Just a separate heads up: the Numpy version is unbound on the upper end. I got Numpy v1.26 probably because OpenMDAO requires Numpy<2. Since the OpenMDAO version is also unbound, if they change then ORBIT may get Numpy v2. This probably isn't a problem for the near term, but just wanted to call it out in case it wasn't on your radar.

[rafmudaf]

Another thing to add to the comment above is that since the expected configs may provide defaults, it is too easy for user to give bad values but get a good-looking result. I just came across this with MooringSystemDesign in the mooring_system_design.mooring_type config. By mistake, I entered the value as a list:

"mooring_system_design": {"mooring_type": ["SemiTaut"]}   # <-- This is incorrect

Since this value is checked by a series of if-statements looking for a specific string, this fell back to the default:

        if self.mooring_type == "SemiTaut":
            ...
        elif self.mooring_type == "TLP":
            ...
        else:
            # Despite "semitaut" being an element in the list, the code goes here to Catenary because it's not checking for a list

Another user error that would cause the same issue is using lower case for these options. In my opinion, this is too subtle for default behavior.

A suggested fix is to check the input types based on the descriptions in the expected_config variables. Also, for text inputs, it might be helpful to either choose one case convention (all lower, snake case, camel case) for all inputs or normalize the case prior to pattern matching (i.e., self.mooring_type.lower() == "semitaut").

[nRiccobo]

Thanks @rafmudaf. I adjusted some of the if-statements and they should be coming in the #173