update documentation

[rb004f]

Branch v07-rc-documentation holds the resolution to this issue

• index.md

  • [x] reference both steady-state and transient optimization

• constraint.md

  • [x] missing docstring errors
  • [x] make a section or sub page for "constraints common to steady-state and transient models"
  • [x] make a section or sub page for "steady state constraints"
  • [x] make a section or sub page for "transient constraints"

• data_format.md

  • [x] double check all field names are correct
  • [x] :heavycheckmark not rendering right in firefox (other browsers as well?)
  • [x] right hand side columns of tables getting chopped off in firefox (other browsers as well?)
  • [x] add discussion on how to add optional and user defined data to the matgas format

• developer.md

  • [x] Add a section which discusses how to create a transient model.
  • [x] Add a section which discusses how to create a steady-state model

• examples.md

  • [x] create this page
  • [x] discuss the examples directory and what is in there. Mention these will move to a GasModelsLib eventually

• formulations.md

  • [x] Add a table indicating the formulations which are supported for steady state and transient models
  • [x] Put the mathematical form of the comment blocks of the constraints so they get rendered in the documenation
  • [x] MISOCP missing constraints
  • [x] MINLP missing constraints

• model.md

  • [x] make a note about using ref_add_transient! in the ref extensions to build a transient model

• math_model.md

  • [x] gas flow section should be rewritten to talk about the derivation (and discretization) of the transient model and then the derivation of the steady-state model
  • [x] add compressor power constraint
  • [x] some constants missing from the list of parameters (i.e., speed of sound)

• network_data.md

  • [x] not rendered. add back in to manual section.
  • [x] update. We basically want to describe the internal dictionary format

• objective.md

  • [x] make a section or sub page for "objectives common to steady-state and transient models"
  • [x] make a section or sub page for "steady state objectives"
  • [x] make a section or sub page for "transient objectives"

• parser.md

  • [x] missing docstring error
  • [x] matgas format discussion is out of date
  • [x] add a csv discussion
  • [x] add a discussion on how to use the i/o to make a transient model

• quickguide.md

  • [x] verify that all instructions work

• result_data.md

  • [x] largely out of date. Needs to be updated to reflect new conventions

• specifications.md

  • [x] make a section for steady-state
  • [x] make a section for transient
  • [x] add transient_ogf
  • [x] double check constraint names are all correct

• variables.md

  • [x] make a section or sub page for "variables common to steady-state and transient models"
  • [x] make a section or sub page for "steady state variables"
  • [x] make a section or sub page for "transient variables"

• [x] add a list of reserved key words that are the optional parameters but are reserved for specific uses. Not sure where this should live. data_format.md?

[rb004f]

@kaarthiksundar I made a list of the places to update the documentation. It is a long list, but most things are < 5 minute changes. I am using the branch v07-rc-documentation to make the edits. I think together we can bang these out pretty quickly. Let me know if you have any questions or disagree

[kaarthiksundar]

@rb004f this looks great. I will get started on this.

[rb004f]

Thanks. If you check off the ones you do it will make sure I don't duplicate your work (I'll do the same)

[kaarthiksundar]

@pseudocubic Can you help me out with the data format points 2 and 3 (the :heavycheckmark and the overflowing columns).

[pseudocubic]

it looks like it should be :heavy_check_mark: for github markdown rendering? I would try that first, if it doesn't work, just replace with Y (or just go straight to step two) I will look into the table rendering, maybe @ccoffrin do you know if there is a way with Documenter.jl to specify table display properties, so that tables that are too wide don't just get chopped off (tables seem to have a property overflow-x: auto; which causes them to turn into horizontally scrollable, rather than display the whole table and make the whole page horizontally scrollable)?

[ccoffrin]

Table display is fixed as far as I know. When it gets too wide you end up with a left-right scrollbar. Not idea but that is workable in a pinch I belive.

[kaarthiksundar]

@rb004f I have ticked most of the transient parts. If you can let me know what other parts you would prefer me do, let me know - I will work on getting them completed.

[rb004f]

@kaarthiksundar Can you do the remaining things in data_format.md, the transient one for developer.md and the transient one for math_model.m? I can then work on the rest... likely tomorrow afternoon or Friday

[kaarthiksundar]

@rb004f The math model, I have added the reference instead of typing out the full equations. I will go ahead and do the equations as and when I find time. I will take care of the data_format.md and the developer.md.

[ccoffrin]

On the topic of math model docs. I recently found a nice way of linking the equations to the function documentation here, https://lanl-ansi.github.io/PowerModels.jl/dev/math-model/

[rb004f]

@kaarthiksundar I think this is largely done. My most recent changes are in the documentation branch of the v0.7 branch. I think I only need two things from you and we close this one. 1) can your added some blocks to network_models.md for storage, transfer and any other component I am forgetting? and 2) can you add some notes in developer.md on how a developer could get started developing their own transient formulation? I am thinking some notes about functions to call which do the discretization, how you maintain links back to the original network model, etc. Once we have that, I think we can merge into the 0.7 branch

[kaarthiksundar]

@rb004f yes and yes. But can we hold off on storage till we have some basic constraints that model storage in place. I will just say the support will be added soon?

[rb004f]

sure. network_models.md just lists the names of fields as the appear in the data dictionary.

[kaarthiksundar]

@pseudocubic I think this is ready for a merge to master. Feel free to take a look and merge when you think it is fine.