Skip to content

Commit

Permalink
Add PyPI link to RTD
Browse files Browse the repository at this point in the history
  • Loading branch information
@c-randall
c-randall committed Nov 13, 2024
1 parent 9f1c257 commit a8c73cc
Show file tree
Hide file tree
Showing 3 changed files with 71 additions and 63 deletions.
2 changes: 1 addition & 1 deletion CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@

### Breaking Changes

## [v1.0.0](https://github.com/NREL/thevenin/tree/v1.0.0)
## [v0.1.0](https://github.com/NREL/thevenin/tree/v0.1.0)
This is the first official release of `thevenin`. Main features/capabilities are listed below.

### Features
Expand Down
116 changes: 62 additions & 54 deletions docs/source/api/thevenin/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -112,8 +112,8 @@ Package Contents
limiting criteria to stop the step early if a specified event/state is
detected.

:param kwargs: IDASolver keyword arguments that will span all steps.
:type kwargs: dict, optional
:param \*\*kwargs: IDASolver keyword arguments that span all steps.
:type \*\*kwargs: dict, optional

.. seealso::

Expand All @@ -125,24 +125,24 @@ Package Contents
Add a step to the experiment.

:param mode: Control mode, from {'current_A', 'voltage_V', 'power_W'}.
:param mode: Control mode, {'current_A', 'current_C', 'voltage_V', 'power_W'}.
:type mode: str
:param value: Value of boundary contion in the appropriate units.
:param value: Value of boundary contion mode, in the appropriate units.
:type value: float | Callable
:param tspan: Relative times for recording solution [s]. Providing a tuple as
(t_max: float, Nt: int) or (t_max: float, dt: float) constructs
tspan using ``np.linspace`` or ``np.arange``, respectively. See
the notes for more information. Given an array simply uses the
values supplied as the evaluation times. Arrays must be monotonic
increasing and start with zero.
tspan using ``np.linspace`` or ``np.arange``, respectively. Given
an array uses the values supplied as the evaluation times. Arrays
must be monotonically increasing and start with zero. See the notes
for more information.
:type tspan: tuple | 1D np.array
:param limits: Stopping criteria for the new step, must be entered in sequential
name/value pairs. Allowable names are {'soc', 'temperature_K',
'current_A', 'voltage_V', 'power_W', 'capacity_Ah', 'time_s',
'time_min', 'time_h'}. Values for each limit should immediately
follow a corresponding name and be the appropriate units. All of
the time limits represent the total experiment time. The default
is None.
'current_A', 'current_C', 'voltage_V', 'power_W', 'capacity_Ah',
'time_s', 'time_min', 'time_h'}. Values for each limit should
immediately follow a corresponding name and match its units. Time
limits are in reference to total experiment time. The default is
None.
:type limits: tuple[str, float], optional
:param \*\*kwargs: IDASolver keyword arguments specific to the new step only.
:type \*\*kwargs: dict, optional
Expand All @@ -166,11 +166,11 @@ Package Contents
.. rubric:: Notes

For time-dependent loads, use a Callable for 'value' with a function
signature like def load(t: float) -> float, where t is the step's
signature like ``def load(t: float) -> float``, where 't' is the step's
relative time, in seconds.

The solution times array is constructed depending on the 'tspan'
input types:
Solution times are constructed and saved depending on the 'tspan' input
types that were supplied:

* Given (float, int):
``tspan = np.linspace(0., tspan[0], tspan[1])``
Expand Down Expand Up @@ -572,8 +572,8 @@ Package Contents

:param params: Mapping of model parameter names to their values. Can be either
a dict or absolute/relateive file path to a yaml file (str). The
keys/value pair descriptions are given below. The default uses a
.yaml file. Use the templates() function to view this file.
keys/value pair descriptions are given below. The default uses an
internal yaml file.

============= ========================== ================
Key Value *type*, units
Expand Down Expand Up @@ -606,10 +606,9 @@ Package Contents
.. rubric:: Notes

The 'ocv' property needs a signature like ``f(soc: float) -> float``,
where 'soc' is the time-dependent state of charged solved for within
the model. All R0, Rj, and Cj properties should have signatures like
``f(soc: float, T_cell: float) -> float``, where 'T_cell' is the cell
temperature in K determined in the model.
where 'soc' is the state of charge. All R0, Rj, and Cj properties need
signatures like ``f(soc: float, T_cell: float) -> float``. 'T_cell' is
the cell temperature in K.

Rj and Cj are not real property names. These are used generally in the
documentation. If ``num_RC_pairs=1`` then in addition to R0, you should
Expand All @@ -626,31 +625,35 @@ Package Contents
This method builds solution pointers, registers algebraic variable
indices, stores the mass matrix, and initializes the battery state.

:param initial_state: Controls how the model state is initialized. If boolean it will set
the state to a rested state at 'soc0' when True (default) or will
bypass the state initialization update when False. Given a Solution
object, the internal state will be set to the final state of the
solution. See notes for more information.
:param initial_state: Control how the model state is initialized. If True (default), the
state is set to a rested condition at 'soc0'. If False, the state
is left untouched and only the parameters and pointers are updated.
Given a Solution instance, the state is set to the final state of
the solution. See notes for more information.
:type initial_state: bool | Solution

:returns: *None.*

.. warning::

This method runs the first time during the class initialization. It
generally does not have to be run again unless you modify any model
attributes. You should manually re-run the pre-processor if you change
any properties after initialization. Forgetting to manually re-run the
pre-processor may cause inconsistencies between the updated properties
and the model's pointers, state, etc.
This method runs during the class initialization. It generally does not
have to be run again unless you modify model properties or attributes.
You should manually re-run the pre-processor if you change properties
after initialization. Forgetting to re-run the pre-processor can cause
inconsistencies between the updated properties and the pointers, state,
etc. If you are updating properties, but want the model's internal state
to not be reset back to a rested condition, use the ``initial_state``
option.

.. rubric:: Notes

Using ``initial_state=False`` will raise an error if you are changing
the size of your circuit (e.g., changing from one to two RC pairs).
The same logic applies when initializing based on a Solution instance.
In other words, a 1RC-pair model cannot be initialized given a solution
from a 2RC-pair circuit.
the size of your circuit (e.g., updating from one to two RC pairs).
Without re-initializing, the model's state vector would be a different
size than the circuit it is trying to solve. For this same reason, when
initializing based on a Solution instance, the solution must also be
the same size as the current model. In other words, a 1RC-pair model
cannot be initialized given a solution from a 2RC-pair circuit.



Expand Down Expand Up @@ -697,28 +700,31 @@ Package Contents

.. py:method:: run(exp, reset_state = True, t_shift = 0.001)
Run an experiment.
Run a full experiment.

:param exp: An experiment instance.
:type exp: Experiment
:param reset_state: If True (default), the internal state of the model will be reset
back to a rested condition at 'soc0' at the end of the experiment.
When False the state does not reset instead matches the final state
of the last experimental step.
back to a rested condition at 'soc0' at the end of all steps. When
False, the state does not reset. Instead it will update to match
the final state of the last experimental step.
:type reset_state: bool
:param t_shift: Time (in seconds) to shift step solutions by when stitching them
together. If zero the end time of each step overlaps the starting
time of its following step. The default is 1e-3.
:type t_shift: float

:returns: :class:`~thevenin.CycleSolution` -- A stitched solution will all experimental steps.
:returns: :class:`~thevenin.CycleSolution` -- A stitched solution with all experimental steps.

.. warning::

The default behavior resets the model's internal state back to a rested
condition at 'soc0' by calling the ``pre()`` method. You can bypass this
by using ``reset_state=False``, which will keep the state at the end of
the final experimental step.
condition at 'soc0' by calling the ``pre()`` method at the end of all
steps. This means that if you run a second experiment afterward, it
will not start where the previous one left off. Instead, it will start
from the original rested condition that the model initialized with. You
can bypass this by using ``reset_state=False``, which keeps the state
at the end of the final experimental step.

.. seealso::

Expand All @@ -739,16 +745,18 @@ Package Contents
:param stepidx: Step index to run. The first step has index 0.
:type stepidx: int

:returns: :class:`~thevenin.StepSolution` -- Solution to the experiment step.
:returns: :class:`~thevenin.StepSolution` -- Solution to the experimental step.

.. warning::

The model's internal state is changed at the end of each experiment
The model's internal state is changed at the end of each experimental
step. Consequently, you should not run steps out of order. You should
always start with ``stepidx = 0`` and then progress to the subsequent
steps afterward. Run ``pre()`` after your last step to reset the state
back to a rested state at 'soc0'. Otherwise the internal state will
match the final state from the last step that was run.
back to a rested condition at 'soc0', if needed. Alternatively, you
can continue running experiments back-to-back without a pre-processing
in between if you want the following experiment to pick up from the
same state that the last experiment ended.

.. seealso::

Expand All @@ -760,11 +768,11 @@ Package Contents

.. rubric:: Notes

Using the ``run()`` method will automatically run all steps in an
experiment and will stitch the solutions together for you. You should
only run step by step if you are trying to fine tune solver options, or
if you have a complex protocol and you can't set an experimental step
until interpreting a previous step.
Using the ``run()`` loops through all steps in an experiment and then
stitches their solutions together. Most of the time, this is more
convenient. However, advantages for running step-by-step is that it
makes it easier to fine tune solver options, and allows for analyses
or control decisions in the middle of an experiment.



Expand Down
16 changes: 8 additions & 8 deletions docs/source/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,13 @@
# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

import thevenin as thev # codespell:ignore thev
import thevenin as thev

project = 'thevenin'
copyright = '2024, Corey R. Randall'
author = 'Corey R. Randall'
version = thev.__version__ # codespell:ignore thev
release = thev.__version__ # codespell:ignore thev
version = thev.__version__
release = thev.__version__


# -- General configuration ---------------------------------------------------
Expand Down Expand Up @@ -75,11 +75,11 @@
'url': 'https://github.com/NREL/thevenin',
'icon': 'fa-brands fa-github',
},
# {
# 'name': 'PyPI',
# 'url': 'https://pypi.org/project/thevenin',
# 'icon': 'fa-solid fa-box',
# },
{
'name': 'PyPI',
'url': 'https://pypi.org/project/thevenin',
'icon': 'fa-solid fa-box',
},
],
'navbar_start': ['navbar-logo'],
'navbar_align': 'content',
Expand Down

0 comments on commit a8c73cc

Please sign in to comment.