Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix/revise the maths formulations #388

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from

Conversation

Jihoon
Copy link
Contributor

@Jihoon Jihoon commented Aug 19, 2020

I find the documentation on the core math formulation is not quite standalone by itself and ends up being quite confusing to external users. It requires filling in or fixing some missing parts to better communicate the formulation doc. I open this PR, but I don't really know answers to all these.

===
Some examples I found:

  1. Equation COST_ACCOUNTING_NODAL
  • The line explaining n^L is not relevant to the equation. Move it where it first appears, and define 'sub-node'
  1. Auxiliary COMMODITY_BALANCE
  • Is it missing 'variable' in the title? i.e. "Auxiliary variable COMMODITY_BALANCE"?
  • Define h^A below the equation
  1. I didn't check all, but multiple equations contain unexplained subscripts, which can only be guessed. (e.g. h^{OD})

  2. Sometimes T^R or L^R is used to mean T^{REN} or L^{REN}.

===
Also, I am not sure whether it is a standard notation in the modeling community, but denoting subsets like N(n_hat) is confusing because it usually means functions. Why don't we use N^{n_hat}, just like it does for T^{REN}.

@khaeru khaeru added this to the 3.2 milestone Dec 18, 2020
@khaeru
Copy link
Member

khaeru commented Jan 14, 2021

@Jihoon since you raise some uncertain issues in the PR description, but I see no response or resolution yet, I will postpone this to v3.3.

I would suggest to explicitly ask specific people for answers those questions; or guess at an appropriate answer and have a discussion with ≥1 other colleague to confirm that the changes are reasonable.

@khaeru khaeru modified the milestones: 3.2, 3.3 Jan 14, 2021
@khaeru khaeru added the docs Documentation label Jan 14, 2021
@khaeru khaeru changed the title Fix/Revise the maths formulations Fix/revise the maths formulations Apr 27, 2021
@khaeru
Copy link
Member

khaeru commented May 24, 2021

Postponed to v3.4:

  • Branch needs a rebase.
  • Questions in the PR description need answering.

@khaeru khaeru modified the milestones: 3.3, 3.4 May 24, 2021
@LauWien
Copy link
Contributor

LauWien commented Jan 19, 2022

I've added the WIP tag, since there is still more time/investigation needed to finish up the PR, as discussed in today's MESSAGEix meeting. Due to that and the following

  • Branch needs a rebase,
  • Questions in the PR description need answering,

we postpone to v3.5.

@LauWien LauWien modified the milestones: 3.4, 3.5 Jan 19, 2022
@LauWien
Copy link
Contributor

LauWien commented Jan 19, 2022

today's MESSAGEix meeting

To bring the PR further, the following tasks and responsibilities have resulted:

@khaeru khaeru marked this pull request as draft March 31, 2022 16:42
@LauWien
Copy link
Contributor

LauWien commented Apr 26, 2022

As this PR is still in the "Draft" stage, we postpone to v3.6.

@LauWien LauWien modified the milestones: 3.5, 3.6 Apr 26, 2022
@khaeru
Copy link
Member

khaeru commented Aug 17, 2022

Removing the milestone entirely. It can be re-added if/when the team decides to schedule/assign the work.

@khaeru khaeru removed this from the 3.6 milestone Aug 17, 2022
@glatterf42
Copy link
Member

As discussed in today's meeting, we should

  1. Merge this PR focussing only on the specific changes identified in its description
  2. Create a tracking issue for further changes
  3. Agree on a consistent notation style (possibly via a dedicated meeting; to be included in a documentation page)
  4. Collect all functions and assign batches of them to multiple reviewers to split the work of ensuring the documentation is consistent with the agreed-upon style

@khaeru khaeru mentioned this pull request Mar 29, 2024
7 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

4 participants