Cite info in README, Coloumbic eff in docs/README, update version_con…

…trol docs for feature/bugfix branch naming

README.md

@@ -31,10 +31,10 @@ This package is a wrapper for the well-known Thevenin equivalent circuit model.
 
 This system is governed by the evolution of the state of charge (SOC, -), RC overpotentials ($V_j$, V), cell voltage ($V_{\rm cell}$, V), and temperature ($T_{\rm cell}$, K). SOC and $V_j$ evolve in time as
 
-$$\frac{d\rm SOC}{dt} = \frac{-I}{3600 Q_{\rm max}},$$
+$$\frac{d\rm SOC}{dt} = \frac{-I \eta_{\rm ce}}{3600 Q_{\rm max}},$$
 $$\frac{dV_j}{dt} = -\frac{V_j}{R_jC_j} + \frac{I}{C_j},$$
 
-where $I$ is the load current (A), $Q_{\rm max}$ is the maximum nominal cell capacity (Ah), and $R_j$ and $C_j$ are the resistance (Ohm) and capacitance (F) of each RC pair $j$. Note that the sign convention for $I$ is chosen such that positive $I$ discharges the battery (reduces SOC) and negative $I$ charges the battery (increases SOC). This convention is consistent with common physics-based models, e.g., the single particle model or pseudo-2D model. While not explicitly included in the equations above, $R_j$ and $C_j$ are functions of SOC and $T_{\rm cell}$. The temperature increases while the cell is active according to
+where $I$ is the load current (A), $Q_{\rm max}$ is the maximum nominal cell capacity (Ah), and $R_j$ and $C_j$ are the resistance (Ohm) and capacitance (F) of each RC pair $j$. $\eta_{\rm ce}$ is the cell's Coulombic efficiency, which is always equal to unity during discharge. Note that the sign convention for $I$ is chosen such that positive $I$ discharges the battery (reduces SOC) and negative $I$ charges the battery (increases SOC). This convention is consistent with common physics-based models, e.g., the single particle model or pseudo-2D model. While not explicitly included in the equations above, $R_j$ and $C_j$ are functions of SOC and $T_{\rm cell}$. The temperature increases while the cell is active according to
 
 $$mC_p\frac{dT_{\rm cell}}{dt} = Q_{\rm gen} + Q_{\rm conv},$$
 
@@ -87,19 +87,19 @@ soln.plot('time_h', 'voltage_V')
 * If you are new to Python, check out [Spyder IDE](https://www.spyder-ide.org/). Spyder is a powerful interactive development environment (IDE) that can make programming in Python more approachable to new users.
 
 ## Citing this Work
-This work was authored by researchers at the National Renewable Energy Laboratory (NREL). The project is tracked in NREL's software records under SWR-24-132 and has a DOI available for citing the work. If you use use this package in your work, please include the following citation:
+This work was authored by researchers at the National Renewable Energy Laboratory (NREL). If you use use this package in your work, please include the following citation:
 
-> Placeholder... waiting for DOI.
+> Randall, Corey R. "thevenin: Equivalent circuit models in Python [SWR-24-132]." Computer software. url: https://github.com/NREL/thevenin. doi: https://doi.org/10.11578/dc.20241125.2.
 
 For convenience, we also provide the following for your BibTex:
 
 ```
-@misc{Randall2024,
-  title = {{thevenin: Equivalent circuit models in Python}},
+@misc{Randall-2024,
+  title = {{thevenin: Equivalent circuit models in Python [SWR-24-132]}},
   author = {Randall, Corey R.},
-  year = {2024},
-  doi = {placeholder... waiting for DOI},
+  doi = {10.11578/dc.20241125.2},
   url = {https://github.com/NREL/thevenin},
+  year = {2024},
 }
 ```
 

docs/source/development/version_control.rst

@@ -49,8 +49,8 @@ Key Features
 3. Feature and Bugfix Branches:
     New features or bug fixes should be developed on separate branches off main. The naming conventions are:
 
-    Feature branches: ``description-issue#``
-    Bugfix branches: ``bug-description-issue#``
+    - Feature branches: ``feature/description-issue``
+    - Bugfix branches: ``bugfix/description-issue``
 
 Note that only bug fixes should have a prefix, but all branches should reference an issue number. Use underscores between works as needed and try to keep to shorter names. The issue can always be referenced in cases where more information is needed.
 
@@ -69,18 +69,25 @@ Always prioritize fixing bugs in the ``main`` branch first. Older releases shoul
 1. Fetch the release branches and create a new branch off the release::
 
     git fetch upstream
-    git checkout -b bug-description-#123 upstream/v1.1.x
+    git checkout -b bugfix/description-123 upstream/v1.1.x
 
 2. Work on your local branch to fix the bug. Commit and push back to your fork as needed::
 
     git add .
     git commit -m "Resolved bug causing ... (#123)"
-    git push origin bug-descriptio-#123
+    git push origin bugfix/description-123
 
 3. Submit a pull request (PR) targeting the specific release branch (e.g., ``v1.1.x``). Only bug fixes should be submitted to release branches -- no new features. Make sure you fill out the pull request template and include more detail than was provided in your commit messages. After all continuous integration (CI) checks are passing, a reviewer will be assigned and will follow up according to the :doc:`review process <review_process>`.
 
 4. If you opened a PR and any CI checks are failing, simply continue working on your branch and committing. All extra commits will automatically be added to the PR.
 
+5. After the PR is accepted and merged into the upstream repository, delete your new branch locally and in your GitHub repo::
+
+    git checkout main
+    git branch -d bugfix/description-123
+    git push origin --delete bugfix/description-123
+    git fetch --prune
+
 6. Repeat this processes as necessary to patch additional older versions. Unfortunately, each version needs to be patched individually, which creates more work for developers, and is the reason we prioritize which versions get patched and which do not. At a minimum, patches should always be applied to all versions between the original patched release and main. For example, patches to ``v1.1.x`` should also be applied for ``v1.2.x`` and above, including ``main``, but do not necessarily need to be submitted for ``v1.0.x``.
 
 .. _New features:
@@ -101,15 +108,15 @@ or, if you setup the ``upstream`` remote, you can do this all in the command lin
 
 You should never commit directly to a ``main`` branch, even including your local or forked ``main`` branch. Instead, your ``main`` branch should always either be synced with the upstream repo, or should simply be behind by some number of commits depending on the last time it was synced. After syncing, create a new branch. Your new branch should be named according to the directions above depending on whether it is a bug fix or for a new feature. Here we demonstrate a new feature::
 
-    git checkout -b branch-name-#456
+    git checkout -b feature/description-456
 
 Once the new branch is created, follow the steps below to add your new feature:
 
 1. Work on your local branch to add the feature. Commit and push back to your fork as needed::
 
     git add .
     git commit -m "Working new feature (#456)"
-    git push origin branch-name-#456
+    git push origin feature/description-456
 
 2. Submit a pull request targeting the upstream ``main`` branch. Make sure you fill out the pull request template and include more detail than was provided in your commit messages.  After all CI checks are passing, a reviewer will be assigned and will follow up according to the :doc:`review process <review_process>`.
 
@@ -118,8 +125,8 @@ Once the new branch is created, follow the steps below to add your new feature:
 4. After the PR is accepted and merged into the upstream repository, delete your new branch locally and in your GitHub repo::
 
     git checkout main
-    git branch -d branch-name-#456
-    git push origin --delete branch-name-#456
+    git branch -d feature/description-456
+    git push origin --delete feature/description-456
     git fetch --prune
 
 Merge Conflicts
@@ -135,7 +142,7 @@ If you've submitted a PR and are seeing merge conflicts you should take the foll
 
 2. Rebase your local bug/feature branch onto ``main``::
 
-    git checkout branch-name-#456
+    git checkout feature/description-456
     git rebase main
 
 3. Address merge conflicts as needed and continue the rebase::

docs/source/user_guide/model_description.rst

@@ -12,11 +12,11 @@ The Thevenin circuit is governed by the evolution of the state of charge (soc, -
 .. math::
 
     \begin{align}
-      &\frac{d\rm soc}{dt} = \frac{-I}{3600 Q_{\rm max}}, \\
+      &\frac{d\rm soc}{dt} = \frac{-I \eta_{\rm ce}}{3600 Q_{\rm max}}, \\
       &\frac{dV_j}{dt} = -\frac{V_j}{R_jC_j} + \frac{I}{C_j},
     \end{align}
 
-where :math:`I` is the load current (A), :math:`Q_{\rm max}` is the maximum nominal cell capacity (Ah), and :math:`R_j` and :math:`C_j` are the resistance (Ohm) and capacitance (F) of each RC pair :math:`j`. Note that the sign convention for :math:`I` is chosen such that positive :math:`I` discharges the battery (reduces soc) and negative :math:`I` charges the battery (increases soc). This convention is consistent with common physics-based models, e.g., the single particle model or pseudo-2D model. While not explicitly included in the equations above, :math:`R_j` and :math:`C_j` are functions of soc and :math:`T_{\rm cell}`. The temperature increases while the cell is active according to
+where :math:`I` is the load current (A), :math:`Q_{\rm max}` is the maximum nominal cell capacity (Ah), and :math:`R_j` and :math:`C_j` are the resistance (Ohm) and capacitance (F) of each RC pair :math:`j`. :math:`\eta_{\rm ce}` is the cell's Coulombic efficiency, which is always equal to unity during discharge. Note that the sign convention for :math:`I` is chosen such that positive :math:`I` discharges the battery (reduces soc) and negative :math:`I` charges the battery (increases soc). This convention is consistent with common physics-based models, e.g., the single particle model or pseudo-2D model. While not explicitly included in the equations above, :math:`R_j` and :math:`C_j` are functions of soc and :math:`T_{\rm cell}`. The temperature increases while the cell is active according to
 
 .. math::