From a8c73ccd2d2766a5fd5139e5deab1f01c54f37ba Mon Sep 17 00:00:00 2001 From: "Corey R. Randall" Date: Wed, 13 Nov 2024 14:01:28 -0700 Subject: [PATCH] Add PyPI link to RTD --- CHANGELOG.md | 2 +- docs/source/api/thevenin/index.rst | 116 +++++++++++++++-------------- docs/source/conf.py | 16 ++-- 3 files changed, 71 insertions(+), 63 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9bb1a0c..769d0f4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/docs/source/api/thevenin/index.rst b/docs/source/api/thevenin/index.rst index 518e0cd..91a95f9 100644 --- a/docs/source/api/thevenin/index.rst +++ b/docs/source/api/thevenin/index.rst @@ -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:: @@ -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 @@ -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])`` @@ -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 @@ -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 @@ -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. @@ -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:: @@ -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:: @@ -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. diff --git a/docs/source/conf.py b/docs/source/conf.py index 30a0d48..d4fc165 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -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 --------------------------------------------------- @@ -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',