From 3c13f0d9c52c4da6e74622f78b25ea867a6c4cf1 Mon Sep 17 00:00:00 2001 From: Nathan Ryan Date: Tue, 20 Feb 2024 12:05:45 -0600 Subject: [PATCH 1/7] initialize docs and standardize docstrings --- Makefile | 20 +++ docs/analysis_doc.rst | 7 + docs/conf.py | 73 +++++++++ docs/create_ar_deployinst_doc.rst | 7 + docs/create_cyclus_input_doc.rst | 7 + docs/dakota_input_doc.rst | 7 + docs/dataframe_analysis_doc.rst | 7 + docs/docs_README.md | 6 + docs/index.rst | 33 ++++ docs/merge_coordinates_doc.rst | 7 + docs/output_metrics_doc.rst | 7 + docs/predicting_the_past_import_doc.rst | 7 + docs/random_lifetime_extension_doc.rst | 7 + docs/scripts_outline.rst | 5 + docs/transition_metrics_doc.rst | 7 + docs/transition_plots_doc.rst | 7 + {docs/gaps => gaps}/Makefile | 0 {docs/gaps => gaps}/acros.tex | 0 {docs/gaps => gaps}/bibliography.bib | 0 {docs/gaps => gaps}/gaps.tex | 0 {docs/gaps => gaps}/images/mox_fuel.png | Bin {docs/gaps => gaps}/images/sfr_fuel.png | Bin make.bat | 35 ++++ requirements.txt | 3 + scripts/analysis.py | 19 ++- scripts/create_AR_DeployInst.py | 131 +++++++-------- scripts/dakota_input.py | 17 +- scripts/dataframe_analysis.py | 112 ++++++------- scripts/output_metrics.py | 154 ++++++++--------- scripts/predicting_the_past_import.py | 16 +- scripts/random_lifetime_extension.py | 2 +- scripts/{README.md => scripts_README.md} | 0 scripts/transition_plots.py | 200 +++++++++++++++++------ 33 files changed, 627 insertions(+), 276 deletions(-) create mode 100644 Makefile create mode 100644 docs/analysis_doc.rst create mode 100644 docs/conf.py create mode 100644 docs/create_ar_deployinst_doc.rst create mode 100644 docs/create_cyclus_input_doc.rst create mode 100644 docs/dakota_input_doc.rst create mode 100644 docs/dataframe_analysis_doc.rst create mode 100644 docs/docs_README.md create mode 100644 docs/index.rst create mode 100644 docs/merge_coordinates_doc.rst create mode 100644 docs/output_metrics_doc.rst create mode 100644 docs/predicting_the_past_import_doc.rst create mode 100644 docs/random_lifetime_extension_doc.rst create mode 100644 docs/scripts_outline.rst create mode 100644 docs/transition_metrics_doc.rst create mode 100644 docs/transition_plots_doc.rst rename {docs/gaps => gaps}/Makefile (100%) rename {docs/gaps => gaps}/acros.tex (100%) rename {docs/gaps => gaps}/bibliography.bib (100%) rename {docs/gaps => gaps}/gaps.tex (100%) rename {docs/gaps => gaps}/images/mox_fuel.png (100%) rename {docs/gaps => gaps}/images/sfr_fuel.png (100%) create mode 100644 make.bat rename scripts/{README.md => scripts_README.md} (100%) diff --git a/Makefile b/Makefile new file mode 100644 index 00000000..3dd4d54b --- /dev/null +++ b/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = docs +BUILDDIR = docs/build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/analysis_doc.rst b/docs/analysis_doc.rst new file mode 100644 index 00000000..e5d550c5 --- /dev/null +++ b/docs/analysis_doc.rst @@ -0,0 +1,7 @@ +Analysis +-------- + +.. automodule:: scripts.analysis + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..0ed3d303 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,73 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys +sys.path.insert(0, os.path.abspath('..')) + + +# -- Project information ----------------------------------------------------- + +project = 'Transition Scenarios' +copyright = '2024, ARFC' +author = 'ARFC' + +# The full version, including alpha/beta/rc tags +release = '0.01' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ['sphinx.ext.autodoc', # generate docs from docstrings + 'sphinx.ext.napoleon', # numpy docstring style + 'm2r2', # allows sphinx to import the readmes from the code + #'sphinx.ext.autosectionlabel', # import autolabel sections + 'sphinx.ext.intersphinx', # make links + +] + +# Suffixes that are useable +source_suffix = { + '.rst': 'restructuredtext', + '.txt': 'markdown', + '.md': 'markdown', +} + +# make sure you have a unique autolabelled target +autosectionlabel_prefix_document = True # Sphinx will create explicit targets for all your sections, the name of target has the form {path/to/page}:{title-of-section}. + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# List of modules to be mocked up. +autodoc_mock_imports = ['pyne', 'fuzzywuzzy','d3ploy','seaborn','xmltodict',''] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'alabaster' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['source/_static'] \ No newline at end of file diff --git a/docs/create_ar_deployinst_doc.rst b/docs/create_ar_deployinst_doc.rst new file mode 100644 index 00000000..66a9957f --- /dev/null +++ b/docs/create_ar_deployinst_doc.rst @@ -0,0 +1,7 @@ +create_AR_DeployInst +-------------------- + +.. automodule:: scripts.create_AR_DeployInst + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/create_cyclus_input_doc.rst b/docs/create_cyclus_input_doc.rst new file mode 100644 index 00000000..3f8450ee --- /dev/null +++ b/docs/create_cyclus_input_doc.rst @@ -0,0 +1,7 @@ +create_cyclus_input +------------------- + +.. automodule:: scripts.create_cyclus_input + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/dakota_input_doc.rst b/docs/dakota_input_doc.rst new file mode 100644 index 00000000..809c3cfb --- /dev/null +++ b/docs/dakota_input_doc.rst @@ -0,0 +1,7 @@ +dakota_input +------------ + +.. automodule:: scripts.dakota_input + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/dataframe_analysis_doc.rst b/docs/dataframe_analysis_doc.rst new file mode 100644 index 00000000..24e98ef3 --- /dev/null +++ b/docs/dataframe_analysis_doc.rst @@ -0,0 +1,7 @@ +dataframe_analysis +------------------ + +.. automodule:: scripts.dataframe_analysis + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/docs_README.md b/docs/docs_README.md new file mode 100644 index 00000000..be1d1e3d --- /dev/null +++ b/docs/docs_README.md @@ -0,0 +1,6 @@ + + + +Requirements +============ + m2r2 diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..58031cef --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,33 @@ +.. Transition Scenarios documentation master file, created by + sphinx-quickstart on Mon Feb 19 13:18:08 2024. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to Transition Scenarios's documentation! +================================================ + +.. toctree:: + :maxdepth: 1 + :caption: Contents: + + scripts_outline + analysis_doc + create_ar_deployinst_doc + create_cyclus_input_doc + dakota_input_doc + dataframe_analysis_doc + merge_coordinates_doc + output_metrics_doc + predicting_the_past_import_doc + random_lifetime_extension_doc + transition_metrics_doc + transition_plots_doc + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + + diff --git a/docs/merge_coordinates_doc.rst b/docs/merge_coordinates_doc.rst new file mode 100644 index 00000000..8e2e932c --- /dev/null +++ b/docs/merge_coordinates_doc.rst @@ -0,0 +1,7 @@ +merge_coordinates +----------------- + +.. automodule:: scripts.merge_coordinates + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/output_metrics_doc.rst b/docs/output_metrics_doc.rst new file mode 100644 index 00000000..ed19b3b6 --- /dev/null +++ b/docs/output_metrics_doc.rst @@ -0,0 +1,7 @@ +output_metrics +-------------- + +.. automodule:: scripts.output_metrics + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/predicting_the_past_import_doc.rst b/docs/predicting_the_past_import_doc.rst new file mode 100644 index 00000000..9b383641 --- /dev/null +++ b/docs/predicting_the_past_import_doc.rst @@ -0,0 +1,7 @@ +predicting_the_past_import +-------------------------- + +.. automodule:: scripts.predicting_the_past_import + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/random_lifetime_extension_doc.rst b/docs/random_lifetime_extension_doc.rst new file mode 100644 index 00000000..c97c9d1b --- /dev/null +++ b/docs/random_lifetime_extension_doc.rst @@ -0,0 +1,7 @@ +random_lifetime_extension +------------------------- + +.. automodule:: scripts.random_lifetime_extension + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/scripts_outline.rst b/docs/scripts_outline.rst new file mode 100644 index 00000000..7d810e14 --- /dev/null +++ b/docs/scripts_outline.rst @@ -0,0 +1,5 @@ +Scripts Overview +================ + +.. mdinclude:: ../scripts/scripts_README.md + diff --git a/docs/transition_metrics_doc.rst b/docs/transition_metrics_doc.rst new file mode 100644 index 00000000..df859a11 --- /dev/null +++ b/docs/transition_metrics_doc.rst @@ -0,0 +1,7 @@ +transition_metrics +------------------ + +.. automodule:: scripts.transition_metrics + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/transition_plots_doc.rst b/docs/transition_plots_doc.rst new file mode 100644 index 00000000..df85ba1c --- /dev/null +++ b/docs/transition_plots_doc.rst @@ -0,0 +1,7 @@ +transition_plots +---------------- + +.. automodule:: scripts.transition_plots + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/gaps/Makefile b/gaps/Makefile similarity index 100% rename from docs/gaps/Makefile rename to gaps/Makefile diff --git a/docs/gaps/acros.tex b/gaps/acros.tex similarity index 100% rename from docs/gaps/acros.tex rename to gaps/acros.tex diff --git a/docs/gaps/bibliography.bib b/gaps/bibliography.bib similarity index 100% rename from docs/gaps/bibliography.bib rename to gaps/bibliography.bib diff --git a/docs/gaps/gaps.tex b/gaps/gaps.tex similarity index 100% rename from docs/gaps/gaps.tex rename to gaps/gaps.tex diff --git a/docs/gaps/images/mox_fuel.png b/gaps/images/mox_fuel.png similarity index 100% rename from docs/gaps/images/mox_fuel.png rename to gaps/images/mox_fuel.png diff --git a/docs/gaps/images/sfr_fuel.png b/gaps/images/sfr_fuel.png similarity index 100% rename from docs/gaps/images/sfr_fuel.png rename to gaps/images/sfr_fuel.png diff --git a/make.bat b/make.bat new file mode 100644 index 00000000..472b6f93 --- /dev/null +++ b/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=docs +set BUILDDIR=docs/build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/requirements.txt b/requirements.txt index 224b857a..283865a4 100644 --- a/requirements.txt +++ b/requirements.txt @@ -6,3 +6,6 @@ pandas pytest matplotlib tables +sphinx +m2r2 +fuzzywuzzy \ No newline at end of file diff --git a/scripts/analysis.py b/scripts/analysis.py index d2d2ed87..27aee954 100644 --- a/scripts/analysis.py +++ b/scripts/analysis.py @@ -687,8 +687,8 @@ def trade_timeseries(cur, sender, receiver, is_cum: bool gets cumulative timeseris if True, monthly value if False - Returns: - -------- + Returns + ------- trades: dictionary if do_isotopic: dictionary with "key=isotope, and @@ -1512,7 +1512,7 @@ def plot_in_out_flux(cur, facility, influx_bool, """Plots timeseries influx/ outflux from facility name in kg. Parameters - --------- + ---------- cur: sqlite cursor sqlite cursor facility: str @@ -1683,7 +1683,7 @@ def entered_power(cur): """Returns dictionary of power entered into simulation. Parameters - --------- + ---------- cur: sqlite cursor sqlite cursor @@ -1781,7 +1781,7 @@ def plot_out_flux_cumulative( title): """Plots timeseries influx/ outflux from facility name in kg. - Parameters: + Parameters ---------- cur: sqlite cursor sqlite cursor @@ -1798,8 +1798,8 @@ def plot_out_flux_cumulative( true: add isotope masses over time false: do not add isotope masses at each timestep - Returns: - -------- + Returns + ------- """ masses = cumulative_mass_timeseries(cur, facility, flux='out') @@ -1917,6 +1917,7 @@ def plot_net_flux( facility, title): """Plots net flux of all isotopes over the duration of the simulation. + Parameters ---------- cur : sqlite cursor @@ -1925,6 +1926,7 @@ def plot_net_flux( name of facility title : str title of plot + Returns ------- plot : plot @@ -1963,6 +1965,7 @@ def mass_timeseries(cur, facility, flux): name of facility flux : str direction of flux + Returns ------- masstime : dict @@ -2041,6 +2044,7 @@ def cumulative_mass_timeseries(cur, facility, flux): name of facility flux : str direction of flux + Returns ------- masstime : dict @@ -2225,6 +2229,7 @@ def plot_cumulative_power(cur, reactors): sqlite cursor reactors : list list of reactors to plot + Returns ------- plot : plot diff --git a/scripts/create_AR_DeployInst.py b/scripts/create_AR_DeployInst.py index 796ba68c..5bd220e6 100644 --- a/scripts/create_AR_DeployInst.py +++ b/scripts/create_AR_DeployInst.py @@ -10,13 +10,13 @@ def convert_xml_to_dict(filename): ''' Reads in an xml file and converts it to a python dictionary - Parameters: - ----------- + Parameters + ---------- filename: str name of xml file - Returns: - -------- + Returns + ------- xml_dict: dict of strings contents of the xml file as a dictionary @@ -37,8 +37,8 @@ def get_deployinst_dict( Only the the prototype names that are in the power_dict are included in the output, so that only prototypes that produce power are considered. - Parameters: - ----------- + Parameters + ---------- deployinst_dict: dict dictionary of DeployInst information. This dictionary is assumed to be nested, with the top key being 'DeployInst', the keys of @@ -52,8 +52,8 @@ def get_deployinst_dict( path: str path to xml files for each prototype - Returns: - -------- + Returns + ------- deployed_dict: dict dictionary of information about LWR prototypes and their deployment. The keys are strs and values are lists of @@ -88,13 +88,13 @@ def get_powers(path): the PRIS database. Assumes that all xml files in the specified directory are for a Cycamore reactor. - Parameters: - ----------- + Parameters + ---------- path: str directory name containing xml files for reactors - Returns: - -------- + Returns + ------- reactor_power: dict dictionary of reactor names and rated powers, the keys are the reactor names (strs), the values are their power outputs (ints). Any spaces @@ -121,8 +121,8 @@ def get_pris_powers(country, path, year): their corresponding rated power output from the reactors_pris_XXXX.csv file for the corresponding year - Parameters: - ----------- + Parameters + ---------- country: str name of country to get LWR data for path: str @@ -130,8 +130,8 @@ def get_pris_powers(country, path, year): year: int year of data to pull from - Returns: - -------- + Returns + ------- pris_power: dict dictionary of reactor names and rated powers, the keys are the reactor names (strs), the values are the rated powers (ints). Any spaces @@ -151,14 +151,14 @@ def get_lifetime(path, name): Get the lifetime of a prototype from a modular file of the prototype definition - Parameters: - ----------- + Parameters + ---------- path: str relative path to prototype definition file name: str name of prototype - Returns: - -------- + Returns + ------- lifetime: int lifetime of prototype ''' @@ -173,8 +173,8 @@ def get_deployed_power(power_dict, deployed_dict, sim_duration): DeployInst. Each entry in the array is for each time step in the simulation. - Parameters: - ----------- + Parameters + ---------- power_dict: dict contains the power output of each agent in the DeployInst. The keys are the reactor @@ -187,8 +187,8 @@ def get_deployed_power(power_dict, deployed_dict, sim_duration): sim_duration: int number of timesteps in the simulation - Returns: - -------- + Returns + ------- t: array of ints ranged arrays of durations inst_power: array of ints @@ -212,15 +212,15 @@ def determine_power_gap(power_profile, demand): Calculates the amount of power needed to be supplied based on the power produced and the demand equation - Parameters: + Parameters ---------- power_profile: array of ints Amount of power produced at each time step demand: array of ints evaluated values of the power demand equation used - Returns: - -------- + Returns + ------- power_gap: array of ints Amount of power needed to meet the power demand. Any negative values from an oversupply of power are changed to 0 @@ -235,14 +235,14 @@ def determine_deployment_order(reactor_prototypes): Creates a list of the keys in reactor_prototypes ordering them in decreasing order of power - Parameters: + Parameters ---------- reactor_prototypes: dict dictionary of information about prototypes in the form {name(str): (power(int), lifetime(int))} - Returns: - -------- + Returns + ------- reactor_order: list of strs ordered list of reactor prototypes in decreasing order of power output. @@ -262,8 +262,8 @@ def update_di(di, prototype, num_reactors, build_time, lifetime): ''' Update a dictionary of a DeployInst - Parameters: - ----------- + Parameters + ---------- di: dictionary dictionary defining the DeployInst, the top-level key is 'DeployInst', the next level keys are 'prototypes', @@ -279,8 +279,8 @@ def update_di(di, prototype, num_reactors, build_time, lifetime): lifetime: int lifetime of the prototype - Returns: - -------- + Returns + ------- di: dictionary updated dictionary to define the DeployInst ''' @@ -303,7 +303,8 @@ def update_power_demand( Subtracts power from the total demand to be filled based on the number of reactors to be deployed - Parameters: + Parameters + ---------- power_gap: list or array demand in power to be filled index: int @@ -319,8 +320,8 @@ def update_power_demand( prototype: str name of prototype to be deployed - Returns: - -------- + Returns + ------- power_gap: array updated values for the power demand after the deployment of a given number of a specified prototype @@ -339,8 +340,8 @@ def deploy_with_share(reactor_prototypes, shares, power, reactor): ''' Deploy prototypes with a defined build share for some or all prototypes - Parameters: - ----------- + Parameters + ---------- reactor_prototypes: dict information about prototypes, {name(str):(power(float),lifetime(int))} @@ -352,8 +353,8 @@ def deploy_with_share(reactor_prototypes, shares, power, reactor): prototype: str name of prototype to be deployed - Returns: - -------- + Returns + ------- num_reactors: int number of the specified prototype to be deployed at a given time step @@ -372,8 +373,8 @@ def deploy_without_share(prototype, reactors, reactor_prototypes, power): ''' Deploy reactors when a build share isn't supplied for the prototype - Parameters: - ----------- + Parameters + ---------- prototype: str name of prototype to be deployed reactors: list of strs @@ -385,8 +386,8 @@ def deploy_without_share(prototype, reactors, reactor_prototypes, power): power: float amount of power that needs to be deployed at a given time step - Returns: - -------- + Returns + ------- num_reactors: int number of the specified prototype to be deployed at a given time step @@ -421,8 +422,8 @@ def redeploy_reactors( number of each prototype deployed while also minimizing the oversupply of energy and minimizing the number of reactors deployed. - Parameters: - ----------- + Parameters + ---------- power: float gap between energy demand and production at a given time step prototype: str @@ -437,8 +438,8 @@ def redeploy_reactors( index of deploy_schedule['DeployInst']['build_times'] in which prototype was deployed at timestep current minus prototype lifetime - Returns: - -------- + Returns + ------- num_reactors: int number of a prototype to deploy ''' @@ -464,8 +465,8 @@ def determine_deployment_schedule( they will be deployed in preferential order based on decreasing power output. - Parameters: - ----------- + Parameters + ---------- power_gap: array gap in power production and demand reactor_prototypes: dictionary @@ -476,8 +477,8 @@ def determine_deployment_schedule( contains information about build share for specified prototypes, {name(str): build share(int)} - Returns: - -------- + Returns + ------- deploy_schedule: dict deployment schedule of reactor prototypes with the structure for a DeployInst @@ -547,8 +548,8 @@ def write_deployinst(deploy_schedule, out_path): ''' Write xml file for the DeployInst to meet the power demand - Parameters: - ----------- + Parameters + ---------- deploy_schedule: dict deployment schedule of reactor prototypes, with the same schema as the DeployInst. Nest dictionary @@ -559,8 +560,8 @@ def write_deployinst(deploy_schedule, out_path): out_path: str path to where the file should be written - Returns: - -------- + Returns + ------- null wites xml file for Cycamore DeployInst ''' @@ -576,8 +577,8 @@ def write_lwr_deployinst(lwr_param, DI_file, lwr_order): is the SinkHLW, leading to the first lifetime item being 600 time steps. - Parameters: - ----------- + Parameters + ---------- lwr_param: float percent of LWRs to receive lifetime extensions DI_file: str @@ -586,8 +587,8 @@ def write_lwr_deployinst(lwr_param, DI_file, lwr_order): lwr_order: str path and name of file containing LWRs ordered by power output. - Returns: - -------- + Returns + ------- DI_dict: dict nested dictionary, contains information for the DeployInst in the form {'DeployInst':{'prototypes':{'val':[]}, 'n_build': @@ -621,8 +622,8 @@ def write_AR_deployinst( '''' Creates the DeployInst for the deployment of advanced reactors - Parameters: - ----------- + Parameters + ---------- lwr_DI: dict dictionary of the DeployInst defining the deployment of LWRs lwr_path: str @@ -641,8 +642,8 @@ def write_AR_deployinst( prototypes, {name(str):build share(int)} - Returns: - -------- + Returns + ------- deploy_schedule: dict nested dictionary, contains information for the DeployInst in the form {'DeployInst':{'prototypes':{'val':[]}, 'n_build': diff --git a/scripts/dakota_input.py b/scripts/dakota_input.py index 2169cb24..5d725cfa 100644 --- a/scripts/dakota_input.py +++ b/scripts/dakota_input.py @@ -2,10 +2,11 @@ def load_template(in_template): - """ Returns a jinja2 template from file. + """ + Returns a jinja2 template from file. Parameters - --------- + ---------- in_template: str path and name of jinja2 template @@ -22,18 +23,18 @@ def render_input(xml_template, variable_dict, input_xml): """ Formats the input file template's placeholder variables - Parameters: - ----------- + Parameters + ---------- xml_template: str path to input file template variable_dict: dict of str - contains the variables in the template file as keys, + contains the variables in the template file as keys, and the value to apply as the value input_xml: str - path to save the filled in template to + path to save the filled in template to - Returns: - -------- + Returns + ------- null """ test_template = load_template(xml_template) diff --git a/scripts/dataframe_analysis.py b/scripts/dataframe_analysis.py index 8f6f90ac..e56cfd02 100644 --- a/scripts/dataframe_analysis.py +++ b/scripts/dataframe_analysis.py @@ -6,13 +6,13 @@ def add_year(df): ''' Adds column of Year, based on the Time column - Parameters: - ----------- + Parameters + ---------- df: DataFrame DataFrame of data to add column for the year to - Returns: - -------- + Returns + ------- df: DataFrame DataFrame with the added column ''' @@ -30,16 +30,16 @@ def add_zeros_columns(df, column_names): greater flexibility in defining prototypes of interest across multiple transition scenarios - Parameters: - ----------- + Parameters + ---------- df: DataFrame dataframe to add column to, if the column doesn't exist already column_names: list of strs names to be checked for existence and added if missing - Returns: - -------- + Returns + ------- df: DataFrame dataframe with added column, if column doesn't exist anymore @@ -55,13 +55,13 @@ def sum_and_add_missing_time(df): Sums the values of the same time step, and adds any missing time steps with 0 for the value - Parameters: - ----------- + Parameters + ---------- df: dataframe dataframe - Returns: - -------- + Returns + ------- summed_df: dataframe dataframe with the summed values for each time step and inserted missing time steps @@ -76,15 +76,15 @@ def find_commodity_transactions(df, commodity): ''' Finds all transactions involving a specified commodity - Parameters: - ----------- + Parameters + ---------- df: dataframe dataframe of transactions commodity: str name of commodity to search for - Returns: - -------- + Returns + ------- commodity_df: dataframe contains only transactions involving the specified commodity ''' @@ -96,15 +96,15 @@ def find_prototype_receiver(df, prototype): ''' Finds all transactions sent to a specified prototype - Parameters: - ----------- + Parameters + ---------- df: dataframe dataframe of transactions prototype: str name of prototype to search for - Returns: - -------- + Returns + ------- prototype_df: dataframe contains only transactions sent to the specified prototype ''' @@ -116,15 +116,15 @@ def find_prototype_sender(transactions_df, prototype): ''' Finds all transactions sent from a specified prototype - Parameters: - ----------- + Parameters + ---------- transactions_df: dataframe dataframe of all transactions prototype: str name of prototype to search for - Returns: - -------- + Returns + ------- prototype_df: dataframe contains only transactions sent from the specified prototype ''' @@ -137,15 +137,15 @@ def commodity_mass_traded(transactions_df, commodity): Calculates the total amount of a commodity traded at each time step - Parameters: - ----------- + Parameters + ---------- transactions_df: dataframe dataframe of all transactions commodity: str commodity name - Returns: - -------- + Returns + ------- total_commodity: DataFrame DataFrame of total amount of each commodity traded as a function of time @@ -163,8 +163,8 @@ def commodity_to_prototype(transactions_df, commodity, prototype): a transaction to the specified prototype, and sums all transactions for a single time step - Parameters: - ----------- + Parameters + ---------- transactions_df: dataframe dataframe of all transactions with the prototype name of the receiver agent added in. use add_receiver_prototype @@ -174,10 +174,10 @@ def commodity_to_prototype(transactions_df, commodity, prototype): prototype: str name of prototype transactions are sent to - Returns: + Returns ------- prototype_transactions: dataframe - contains summed transactions at each time step of the + contains summed transactions at each time step of the spcified commodity that are sent to the specified prototype name. ''' @@ -194,15 +194,15 @@ def transactions_to_prototype(transactions_df, prototype): ''' Finds all transactions to a prototype - Parameters: - ----------- + Parameters + ---------- transactions_df: DataFrame prototype: str - Returns: - -------- + Returns + ------- prototype_transactions: DataFrame - contains summed transactions at each time step that + contains summed transactions at each time step that are sent to the specified prototype name. ''' prototype_transactions = find_prototype_receiver( @@ -219,8 +219,8 @@ def commodity_from_prototype(transactions_df, commodity, prototype): a transaction to the specified prototype, and sums all transactions for a single time step - Parameters: - ----------- + Parameters + ---------- transactions_df: dataframe dataframe of all transactions with the prototype name of the receiver agent added in. use add_receiver_prototype to get this @@ -230,7 +230,7 @@ def commodity_from_prototype(transactions_df, commodity, prototype): prototype: str name of prototype transactions are sent to - Returns: + Returns ------- prototype_transactions: dataframe contains summed transactions at each time step that are sent to @@ -253,8 +253,8 @@ def commodity_to_LWR(transactions_df, commodity, prototype): a single time step. The LWRs are assigned to any prototype name not given to this function. - Parameters: - ----------- + Parameters + ---------- transactions_df: dataframe dataframe of transactions with the prototype name of the receiver agent added in, use add_receiver_prototype to get this @@ -264,7 +264,7 @@ def commodity_to_LWR(transactions_df, commodity, prototype): prototype: list of str name(s) of non-LWR reactor prototype(s) in the simulation - Returns: + Returns ------- prototype_transactions: dataframe contains summed transactions at each time step that are sent to @@ -284,13 +284,13 @@ def separation_potential(x_i): Calculates Separation Potential, for use in calculating Separative Work Units (SWU) required for enrichment level. - Inputs: - ------- + Parameters + ---------- x_i: int mass fraction of a generic mass stream - Returns: - -------- + Returns + ------- v: int Separation potential ''' @@ -304,8 +304,8 @@ def calculate_SWU(P, x_p, T, x_t, F, x_f): throughput of product given the mass of feed and tails, and the assay of each mass stream. - Parameters: - ----------- + Parameters + ---------- P: int, Series mass of product x_p: int @@ -319,8 +319,8 @@ def calculate_SWU(P, x_p, T, x_t, F, x_f): x_f: int weight percent of U-235 in feed - Returns: - -------- + Returns + ------- SWU: int Separative Work units per unit time ''' @@ -335,7 +335,7 @@ def calculate_tails(product, x_p, x_t, x_f): a mass of product and the mass fraction of the product, tails, and feed - Parameters: + Parameters ---------- product: int, Series mass of product @@ -346,7 +346,7 @@ def calculate_tails(product, x_p, x_t, x_f): x_f: float mass fraction of feed - Returns: + Returns ------- tails: int, Series mass of tails @@ -361,15 +361,15 @@ def calculate_feed(product, tails): to produce a given amount of product and tails. - Parameters: + Parameters ---------- product: int, Series mass of product tails: int, Series mass of tails - Returns: - -------- + Returns + ------- feed: int, Series mass of feed material ''' diff --git a/scripts/output_metrics.py b/scripts/output_metrics.py index 6a52475c..6e3a6927 100644 --- a/scripts/output_metrics.py +++ b/scripts/output_metrics.py @@ -29,8 +29,8 @@ def merge_and_fillna_col(left, right, lcol, rcol, how='left', on=None): on : list of str, optional Which columns to merge on, same as in pd.merge() - Returns: - -------- + Returns + ------- left: DataFrame Merged dataframe with any NaN values replaced with values from the specified column @@ -49,15 +49,15 @@ def get_table_from_output(db_file, table_name): issues experienced, and only the columns called here were used for later functions. - Parameters: - ----------- + Parameters + ---------- db_file: str filename of database table_name: str name of table in the database - Returns: - -------- + Returns + ------- table_df: DataFrame requested table from database ''' @@ -75,13 +75,13 @@ def create_agents_table(db_file): ''' Recreates the Agents metric in cymetric. - Parameters: - ----------- + Parameters + ---------- db_file: str filename of database - Returns: - -------- + Returns + ------- agents: DataFrame recreated Agents metric ''' @@ -115,13 +115,13 @@ def merge_transactions_resources(db_file): to create a DataFrame with the quantity of each material transaction. - Parameters: - ----------- + Parameters + ---------- db_file: str SQLite database from Cyclus - Returns: - -------- + Returns + ------- trans_resources: DataFrame merged DataFrame containing the quantity of the material in each transaction @@ -146,13 +146,13 @@ def add_receiver_prototype(db_file): AgentId column renamed to ReceiverId to assist the merge process. The final dataframe is organized by ascending order of Time then TransactionId. - Parameters: - ----------- + Parameters + ---------- db_file: str SQLite database from Cyclus - Returns: - -------- + Returns + ------- receiver_prototype: dataframe contains all of the transactions with the prototype name of the receiver included @@ -176,13 +176,13 @@ def add_sender_prototype(db_file): AgentId column renamed to SenderId to assist the merge process. The final dataframe is organized by ascending order of Time then TransactionId. - Parameters: - ----------- + Parameters + ---------- db_file: str SQLite database from Cyclus - Returns: - -------- + Returns + ------- sender_prototype: DataFrame contains all of the transactions with the prototype name of the receiver included @@ -203,8 +203,8 @@ def get_multiple_prototype_transactions(db_file, prototypes, commodity): Gets the transactions of the given commodity sent to the specified prototypes in each time step. - Parameters: - ----------- + Parameters + ---------- db_file: str name of database file prototypes: list of strs @@ -212,8 +212,8 @@ def get_multiple_prototype_transactions(db_file, prototypes, commodity): commodity: str name of commodity - Returns: - -------- + Returns + ------- commodity_transactions: DataFrame DataFrame of transactions for commodity to specific prototypes. The mass sent to each prototype is in a separate column, with @@ -234,8 +234,8 @@ def get_enriched_u_mass(db_file, prototypes, transition_start): is calculated from the start of the transition to the end of the simulation. - Parameters: - ----------- + Parameters + ---------- db_file: str name of database file prototypes: list of str @@ -243,8 +243,8 @@ def get_enriched_u_mass(db_file, prototypes, transition_start): transition_start: int time step the modeled transition begins at - Returns: - -------- + Returns + ------- cumulative_u: float the cumulative mass of enriched uranium sent to specified prototypes starting at the transition start time @@ -263,8 +263,8 @@ def calculate_feed(db_file, prototypes, transition_start): Calculate the cumulative feed uranium needed to create enriched uranium for the specified prototypes - Parameters: - ----------- + Parameters + ---------- db_file: str name of database file prototypes: list of strs @@ -272,8 +272,8 @@ def calculate_feed(db_file, prototypes, transition_start): transition_start: int time step the modeled transition begins at - Returns: - -------- + Returns + ------- cumulative_feed: float The total feed uranium required for the prototypes, starting at the transition start time. @@ -300,8 +300,8 @@ def calculate_swu(db_file, prototypes, transition_start): Calculates the cumulative amount of SWU capacity required to create the enriched uranium in the simulation. - Parameters: - ----------- + Parameters + ---------- db_file: str name of database file prototypes: list of strs @@ -315,8 +315,8 @@ def calculate_swu(db_file, prototypes, transition_start): contain the assays for the tails and feed streams, and be labeled as 'tails' and 'feed' - Returns: - -------- + Returns + ------- cumulative_swu: float the average SWU capacity required for the simulation, starting at the transition start time @@ -351,8 +351,8 @@ def get_waste_discharged(db_file, prototypes, transition_start, commodities): sums them together and provides a cumulative total from the start of the transition. - Parameters: - ----------- + Parameters + ---------- db_file: str name of database file prototypes: list of strs @@ -363,8 +363,8 @@ def get_waste_discharged(db_file, prototypes, transition_start, commodities): name of waste commodity for each prototype, in the form {prototype name (str): commodity name(str)} - Returns: - -------- + Returns + ------- waste_discharged: float cumulative waste discharged from all specified prototypes ''' @@ -383,13 +383,13 @@ def get_annual_electricity_table(db_file): Get the table of the annual electricity produced by each agent in a simulation - Parameters: - ----------- + Parameters + ---------- db_file: str file name of database - Returns: - -------- + Returns + ------- annual_electricity: DataFrame Contains the SimId, AgentId, Year, and Energy from the database ''' @@ -408,15 +408,15 @@ def get_annual_electricity_table(db_file): def get_annual_electricity(db_file): ''' Gets the time dependent annual electricity output of reactors - in the silumation + in the simulation - Parameters: - ----------- + Parameters + ---------- db_file: str file name of database - Returns: - -------- + Returns + ------- electricity_output: DataFrame time dependent electricity output, includes column for year of time step. The energy column @@ -438,15 +438,15 @@ def get_prototype_energy(db_file, advanced_rx): prototype name by merging the Agents and AnnualElectricityGeneratedByAgent dataframes so that agents can be grouped by prototype name - Parameters: - ----------- + Parameters + ---------- db_file: str file name of database advanced_rx: str name of advanced reactor prototype - Returns: - -------- + Returns + ------- prototype_energy: dataframe dataframe of the year and the total amount of electricity generated by all agents of the given prototype name. Values @@ -471,15 +471,15 @@ def get_lwr_energy(db_file, advanced_rx): prototype name by merging the Agents and AnnualElectricityGeneratedByAgent dataframes so that agents can be grouped by prototype name - Parameters: - ----------- + Parameters + ---------- db_file: str file name of database advanced_rx: list of strs name(s) of advanced reactor prototype also present in the simulation - Returns: - -------- + Returns + ------- lwr_energy: dataframe dataframe of the year and the total amount of electricity generated by all of the LWRs in the simulation. The energy @@ -499,22 +499,22 @@ def get_lwr_energy(db_file, advanced_rx): def get_all_results(results, output_sqlite): ''' - Calls multiple functions in this script at the same time to get all + Calls multiple functions in this script at the same time to get all metrics from the output files and return them to Dakota. - Metrics include the total mass of enriched uranium, mass of - HALEU, SWU capacity, SWU capacity to produce HALEU, feed mass to - produce HALEU, and the total mass of spent nuclear fuel - discharged. + Metrics include the total mass of enriched uranium, mass of + HALEU, SWU capacity, SWU capacity to produce HALEU, feed mass to + produce HALEU, and the total mass of spent nuclear fuel + discharged. - Parameters: - ----------- + Parameters + ---------- results: obj results passed to Dakota output_sqlite: str file name for Cyclus output SQLite file - Returns: - -------- + Returns + ------- results: obj results passed to Dakota ''' @@ -546,22 +546,22 @@ def get_all_results(results, output_sqlite): def run_cyclus(output_sqlite, input_xml): ''' - Define the Cyclus output file name, and run cyclus with a given + Define the Cyclus output file name, and run cyclus with a given input file name. - Parameters: - ----------- + Parameters + ---------- output_sqlite: str name of Cyclus SQLite output file input_xml: str - name of Cyclus xml input file + name of Cyclus xml input file + + Returns + ------- + null - Returns: - -------- - null - ''' if not os.path.exists(output_sqlite): os.system('cyclus -i ' + input_xml + ' -o ' + output_sqlite + ' --warn-limit 2') - + diff --git a/scripts/predicting_the_past_import.py b/scripts/predicting_the_past_import.py index 5ec45abe..aafe2dd4 100644 --- a/scripts/predicting_the_past_import.py +++ b/scripts/predicting_the_past_import.py @@ -249,7 +249,7 @@ def import_csv(in_csv, delimit=','): lists. Parameters - --------- + ---------- in_csv: str path and name of input csv file delimit: str @@ -272,7 +272,7 @@ def load_template(in_template): """ Returns a jinja2 template from file. Parameters - --------- + ---------- in_template: str path and name of jinja2 template @@ -290,7 +290,7 @@ def get_composition_fresh(in_list, burnup): using vision_recipes for fresh UOX fuel. Parameters - --------- + ---------- in_list: list list containing vision_recipes burnup: int @@ -322,7 +322,7 @@ def get_composition_spent(in_list, burnup): using vision_recipes for spent nuclear fuel Parameters - --------- + ---------- in_list: list list containing vision_recipes data burnup: int @@ -354,7 +354,7 @@ def write_recipes(fresh_dict, spent_dict, in_template, """ Renders jinja template using fresh and spent fuel composition. Parameters - --------- + ---------- fresh_dict: dict dictionary with key=[isotope], and value=[composition] for fresh UOX @@ -384,7 +384,7 @@ def produce_recipes(in_csv, recipe_template, burnup, out_path): """ Generates commodity composition xml input for cyclus. Parameters - --------- + ---------- in_csv: str path and name of recipe file recipe_template: str @@ -657,7 +657,7 @@ def write_deployment(in_dict, out_path, deployinst_template, located in cyclus_input/reactors. Parameters - --------- + ---------- in_dict: dictionary dictionary with key=[reactor name], and value=[buildtime] out_path: str @@ -738,7 +738,7 @@ def deploy_reactors(in_csv, region, start_year, deployinst_template, in a CYCLUS simulation. Parameters - --------- + ---------- in_csv: str path to pris reactor database region: str diff --git a/scripts/random_lifetime_extension.py b/scripts/random_lifetime_extension.py index c5b6899f..e04d9801 100644 --- a/scripts/random_lifetime_extension.py +++ b/scripts/random_lifetime_extension.py @@ -8,7 +8,7 @@ def generate_input(input_path, output_path, orig_lifetime, """This function takes a full Cyclus input xml file, finds the DeployInst block for the country, and extends the lifetime of LWR reactors - according to a Gaussian distribution (mean 10, sd 3 [years]) + according to a Gaussian distribution (mean 10, sd 3 [years]). Parameters ---------- diff --git a/scripts/README.md b/scripts/scripts_README.md similarity index 100% rename from scripts/README.md rename to scripts/scripts_README.md diff --git a/scripts/transition_plots.py b/scripts/transition_plots.py index 7a4f84e4..b8e92c92 100644 --- a/scripts/transition_plots.py +++ b/scripts/transition_plots.py @@ -12,14 +12,20 @@ def format_agent_dict(output_file, simple=True): sqlite file and creates a time series dictionary of the entry the various facilities in the simulation. The output of this function is used as an input for the plot_agents function to generate nice deployment plots. - INPUT - output_file: sqlite file name (str) - simple: boolean. - True: EG01-23, EG01-24 - False: EG01-29, EG01-30 - OUTPUT - agent_dict: time series dictionary of the entry the various - facilities in the simulation (dict) + + Parameters + ---------- + output_file : str + sqlite file name + simple : boolean. + True: EG01-23, EG01-24 + False: EG01-29, EG01-30 + + Returns + ------- + agent_dict : dict + Time series dictionary of the entry the various + facilities in the simulation. """ if simple: @@ -123,14 +129,19 @@ def plot_agents(all_agents, name, simple=True): This function takes the time series facility entry dictionary output from the format_agent_dict function to generate two deployment plots: reactors and supporting fuel cycle facilities. - INPUT - agent_dict: time series dictionary of the entry the various - facilities in the simulation (dict) - simple: boolean. - True: EG01-23, EG01-24 - False: EG01-29, EG01-30 - OUTPUT - Two plots (reactor and supporting fuel cycle facility plots) + + Parameters + ---------- + agent_dict : dict + Time series dictionary of the entry the various + facilities in the simulation. + simple : boolean. + True: EG01-23, EG01-24 + False: EG01-29, EG01-30 + + Returns + ------- + Two plots (reactor and supporting fuel cycle facility plots). """ fig, ax = plt.subplots(figsize=(15, 7)) ax.grid(alpha=0.7) @@ -244,12 +255,18 @@ def supplydemanddiff(all_dict): """ This function calculates the difference between supply and demand from all_dict. - INPUT - all_dict: dictionary with supply and demand timeseries - data for a commodity. (dict) - OUTPUT - diff_dict: dictionary with timeseries data of the difference - between supply and demand. + + Parameters + ---------- + all_dict : dict + Dictionary with supply and demand timeseries + data for a commodity. + + Returns + ------- + diff_dict : dict + Dictionary with timeseries data of the difference + between supply and demand. """ dict_demand = all_dict['dict_demand'] @@ -267,22 +284,31 @@ def get_undersupply_timesteps( demand_eq='0', demand_driving=True): """ - This function returns timeseries dictionaries for existence - undersupply of a commodity and the - absolute value of this undersupply. - INPUT - output_file: sqlite file (str) - commod: commodity name (str) - driving_commod: Boolean, True: driving commod, False: not driving commod - demand_eq: demand equation (str), only used if driving_commod is True - demand_driving: Boolean. - True: demand-driven commodities - False: supply-driven commodities - OUTPUT - dict_dots: timeseries dictionary with 1 and 0 depending if there is - undersupply at a specific time step. - diff_dict_drop: timeseries dictionary with absolute difference between - supply and demand, if supply < demand. + Returns timeseries dictionaries for existence of undersupply of a commodity + and the absolute value of this undersupply. + + Parameters + ---------- + output_file : str + Path to the SQLite file. + commod : str + Name of the commodity. + driving_commod : bool, optional + Indicates if the commodity is a driving commodity (True) or not (False). + Defaults to False. + demand_eq : str, optional + Demand equation, only used if driving_commod is True. + Defaults to '0'. + demand_driving : bool, optional + Indicates whether the commodities are demand-driven (True) or supply-driven (False). + Defaults to True. + + Returns + ------- + dict_dots : dict + Timeseries dictionary with 1 and 0 indicating undersupply at specific time steps. + diff_dict_drop : dict + Timeseries dictionary with absolute difference between supply and demand, if supply < demand. """ if driving_commod: @@ -321,22 +347,32 @@ def plot_all_undersupply( title='', name='hello'): """ - This function generates a comparison of commodity undersupply for different - prediction methods plot. - INPUT - commods: list of commods (list of str) - commodnames: list of commod names to show in the y axis of plot - (list of str) - methods: list of methods (list of str) - general_sqlite: name of sqlite without method name added at end (str) - demand_driven: Boolean. - True: demand-driven commodities - False: supply-driven commodities - demand_eq: power demand equation (str) - title: title of plot (str) - name: name of figure png (str) - OUTPUT - Comparison of commodity undersupply for different prediction methods plot + Generates a comparison plot of commodity undersupply for different prediction methods. + + Parameters + ---------- + commods : list of str + List of commodities. + commodnames : list of str + List of commodity names to display on the y-axis of the plot. + methods : list of str + List of prediction methods. + general_sqlite : str + Name of the SQLite database without the method name added at the end. + demand_driven : bool, optional + Boolean indicating whether the commodities are demand-driven (True) or supply-driven (False). + Defaults to True. + demand_eq : str, optional + Equation for power demand. Defaults to '0'. + title : str, optional + Title of the plot. Defaults to an empty string. + name : str, optional + Name of the PNG file for the figure. Defaults to an empty string. + + Returns + ------- + None : + Saves plots named according to the name argument. """ num = len(commods) * 1.5 @@ -429,6 +465,30 @@ def histogram_formatting( general_sqlite, demand_driven=True, demand_eq='0'): + """ + Formats data for generating histograms of undersupplied time steps. + + Parameters + ---------- + commods : list + List of commodities. + methods : list + List of prediction methods. + general_sqlite : str + General SQLite database filename path. + demand_driven : bool, optional + Flag indicating if demand-driven mode is enabled (default is True). + demand_eq : str, optional + Equation for demand (default is '0'). + + Returns + ------- + dict + A dictionary containing formatted data for generating histograms. + The keys are prediction methods, and the values are dictionaries + where the keys are commodities and the values are arrays representing + histogram bin values. + """ everything = {} for y in methods: everything[y] = {} @@ -463,6 +523,38 @@ def plot_histogram( title, name, yticks): + """ + Plots a histogram comparing undersupplied time steps for different commodities and prediction methods. + + Parameters + ---------- + commods1 : list + List of commodities for dataset 1. + commodnames1 : list + Names of commodities for dataset 1. + commods2 : list + List of commodities for dataset 2. + commodnames2 : list + Names of commodities for dataset 2. + methods : list + List of prediction methods. + methodnames : list + Names of prediction methods. + general_sqlite : object + Object for handling SQLite database. + demand_eq : bool + Boolean indicating whether demand-driven mode is enabled. + title : str + Title for the histogram plot. + name : str + Name of the file to save the plot. + yticks : list + List of values for y-axis ticks. + + Returns + ------- + None + """ everything1 = histogram_formatting( commods=commods1, methods=methods, From fe9e394c6cacf19486d394a6dc23b6faf9b6733d Mon Sep 17 00:00:00 2001 From: Nathan Ryan Date: Thu, 22 Feb 2024 14:46:03 -0600 Subject: [PATCH 2/7] update docstrings to be consistent, and create a working version of the base docs --- docs/conf.py | 42 +++++++++++---- docs/create_ar_deployinst_doc.rst | 2 +- docs/create_cyclus_input_doc.rst | 2 +- docs/dakota_input_doc.rst | 2 +- docs/dataframe_analysis_doc.rst | 2 +- docs/index.md | 29 ++++++++++ docs/index.rst | 33 ------------ docs/merge_coordinates_doc.rst | 2 +- docs/output_metrics_doc.rst | 2 +- docs/predicting_the_past_import_doc.rst | 4 +- docs/random_lifetime_extension_doc.rst | 2 +- docs/scripts_outline.md | 4 ++ docs/scripts_outline.rst | 5 -- docs/transition_metrics_doc.rst | 2 +- docs/transition_plots_doc.rst | 2 +- scripts/create_cyclus_input.py | 2 - scripts/dataframe_analysis.py | 1 - scripts/output_metrics.py | 22 ++++---- scripts/predicting_the_past_import.py | 16 +++--- scripts/transition_metrics.py | 72 ++++++++++++------------- 20 files changed, 130 insertions(+), 118 deletions(-) create mode 100644 docs/index.md delete mode 100644 docs/index.rst create mode 100644 docs/scripts_outline.md delete mode 100644 docs/scripts_outline.rst diff --git a/docs/conf.py b/docs/conf.py index 0ed3d303..3e85cef3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -12,7 +12,7 @@ # import os import sys -sys.path.insert(0, os.path.abspath('..')) +sys.path.insert(0, os.path.abspath('../')) # -- Project information ----------------------------------------------------- @@ -30,20 +30,32 @@ # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['sphinx.ext.autodoc', # generate docs from docstrings - 'sphinx.ext.napoleon', # numpy docstring style - 'm2r2', # allows sphinx to import the readmes from the code +extensions = [#'sphinx.ext.autodoc', # generate docs from docstrings + #'sphinx.ext.napoleon', # numpy docstring style + #'m2r2', # allows sphinx to import the readmes from the code #'sphinx.ext.autosectionlabel', # import autolabel sections - 'sphinx.ext.intersphinx', # make links + #'sphinx.ext.intersphinx', # make links + "myst_parser", # Adds support for Markedly Structured Text, includes more features + "sphinx.ext.napoleon", # Numpy docstring style + "sphinx.ext.duration", # Represent time durations in a human-readable format + "sphinx.ext.autosectionlabel", # Labels sections + "sphinx.ext.autodoc", # Generate docs from docstrings + "sphinx.ext.autosummary", # Generates summary tables of contents for modules and packages + "sphinx.ext.intersphinx", # Linking to external documentation sites + "sphinx.ext.viewcode", # Adds "View Source" links to docs + "sphinx.ext.mathjax", # Render mathematical expressions written in LaTeX + "sphinx.ext.coverage", # Assessing and visualizing the test coverage + "nbsphinx", # Include Jupyter Notebooks in docs + "sphinxcontrib.mermaid" # Create diagrams in markdown ] # Suffixes that are useable -source_suffix = { - '.rst': 'restructuredtext', - '.txt': 'markdown', - '.md': 'markdown', -} +# source_suffix = { +# '.rst': 'restructuredtext', +# '.txt': 'markdown', +# '.md': 'markdown', +# } # make sure you have a unique autolabelled target autosectionlabel_prefix_document = True # Sphinx will create explicit targets for all your sections, the name of target has the form {path/to/page}:{title-of-section}. @@ -57,7 +69,15 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] # List of modules to be mocked up. -autodoc_mock_imports = ['pyne', 'fuzzywuzzy','d3ploy','seaborn','xmltodict',''] +autodoc_mock_imports = ['pyne', 'd3ploy','seaborn','xmltodict', 'dataframe_analysis','predicting_the_past_import', 'create_AR_DeployInst'] + +intersphinx_mapping = { + 'python': ('https://docs.python.org/3', None), + 'pandas':('https://pandas.pydata.org/docs/', None), + 'numpy': ('https://numpy.org/doc/stable/', None), + 'astropy': ('https://docs.astropy.org/en/stable/', None), + 'cyclus': ('https://fuelcycle.org/', None) +} # -- Options for HTML output ------------------------------------------------- diff --git a/docs/create_ar_deployinst_doc.rst b/docs/create_ar_deployinst_doc.rst index 66a9957f..49555ea8 100644 --- a/docs/create_ar_deployinst_doc.rst +++ b/docs/create_ar_deployinst_doc.rst @@ -1,4 +1,4 @@ -create_AR_DeployInst +Create AR DeployInst -------------------- .. automodule:: scripts.create_AR_DeployInst diff --git a/docs/create_cyclus_input_doc.rst b/docs/create_cyclus_input_doc.rst index 3f8450ee..37ae2530 100644 --- a/docs/create_cyclus_input_doc.rst +++ b/docs/create_cyclus_input_doc.rst @@ -1,4 +1,4 @@ -create_cyclus_input +Create Cyclus Input ------------------- .. automodule:: scripts.create_cyclus_input diff --git a/docs/dakota_input_doc.rst b/docs/dakota_input_doc.rst index 809c3cfb..8ba68e4a 100644 --- a/docs/dakota_input_doc.rst +++ b/docs/dakota_input_doc.rst @@ -1,4 +1,4 @@ -dakota_input +Dakota Input ------------ .. automodule:: scripts.dakota_input diff --git a/docs/dataframe_analysis_doc.rst b/docs/dataframe_analysis_doc.rst index 24e98ef3..26e98b33 100644 --- a/docs/dataframe_analysis_doc.rst +++ b/docs/dataframe_analysis_doc.rst @@ -1,4 +1,4 @@ -dataframe_analysis +Dataframe Analysis ------------------ .. automodule:: scripts.dataframe_analysis diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..e376a3a2 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,29 @@ + + +# Welcome to Transition Scenarios's documentation! + +```{toctree} +:maxdepth: 1 + +scripts_outline +analysis_doc +create_ar_deployinst_doc +create_cyclus_input_doc +dakota_input_doc +dataframe_analysis_doc +merge_coordinates_doc +output_metrics_doc +predicting_the_past_import_doc +random_lifetime_extension_doc +transition_metrics_doc +transition_plots_doc +``` + +# Indices and tables + +- {ref}`genindex` +- {ref}`modindex` +- {ref}`search` \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 58031cef..00000000 --- a/docs/index.rst +++ /dev/null @@ -1,33 +0,0 @@ -.. Transition Scenarios documentation master file, created by - sphinx-quickstart on Mon Feb 19 13:18:08 2024. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Welcome to Transition Scenarios's documentation! -================================================ - -.. toctree:: - :maxdepth: 1 - :caption: Contents: - - scripts_outline - analysis_doc - create_ar_deployinst_doc - create_cyclus_input_doc - dakota_input_doc - dataframe_analysis_doc - merge_coordinates_doc - output_metrics_doc - predicting_the_past_import_doc - random_lifetime_extension_doc - transition_metrics_doc - transition_plots_doc - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - - diff --git a/docs/merge_coordinates_doc.rst b/docs/merge_coordinates_doc.rst index 8e2e932c..a1ec44d3 100644 --- a/docs/merge_coordinates_doc.rst +++ b/docs/merge_coordinates_doc.rst @@ -1,4 +1,4 @@ -merge_coordinates +Merge Coordinates ----------------- .. automodule:: scripts.merge_coordinates diff --git a/docs/output_metrics_doc.rst b/docs/output_metrics_doc.rst index ed19b3b6..83f5af91 100644 --- a/docs/output_metrics_doc.rst +++ b/docs/output_metrics_doc.rst @@ -1,4 +1,4 @@ -output_metrics +Output Metrics -------------- .. automodule:: scripts.output_metrics diff --git a/docs/predicting_the_past_import_doc.rst b/docs/predicting_the_past_import_doc.rst index 9b383641..d28620df 100644 --- a/docs/predicting_the_past_import_doc.rst +++ b/docs/predicting_the_past_import_doc.rst @@ -1,5 +1,5 @@ -predicting_the_past_import --------------------------- +Predicting the Past +------------------- .. automodule:: scripts.predicting_the_past_import :members: diff --git a/docs/random_lifetime_extension_doc.rst b/docs/random_lifetime_extension_doc.rst index c97c9d1b..282fcf8c 100644 --- a/docs/random_lifetime_extension_doc.rst +++ b/docs/random_lifetime_extension_doc.rst @@ -1,4 +1,4 @@ -random_lifetime_extension +Random Lifetime Extension ------------------------- .. automodule:: scripts.random_lifetime_extension diff --git a/docs/scripts_outline.md b/docs/scripts_outline.md new file mode 100644 index 00000000..9ac292c2 --- /dev/null +++ b/docs/scripts_outline.md @@ -0,0 +1,4 @@ +# Scripts Outline + +```{include} ../scripts/scripts_README.md +``` diff --git a/docs/scripts_outline.rst b/docs/scripts_outline.rst deleted file mode 100644 index 7d810e14..00000000 --- a/docs/scripts_outline.rst +++ /dev/null @@ -1,5 +0,0 @@ -Scripts Overview -================ - -.. mdinclude:: ../scripts/scripts_README.md - diff --git a/docs/transition_metrics_doc.rst b/docs/transition_metrics_doc.rst index df859a11..ab3e0091 100644 --- a/docs/transition_metrics_doc.rst +++ b/docs/transition_metrics_doc.rst @@ -1,4 +1,4 @@ -transition_metrics +Transition Metrics ------------------ .. automodule:: scripts.transition_metrics diff --git a/docs/transition_plots_doc.rst b/docs/transition_plots_doc.rst index df85ba1c..5c092076 100644 --- a/docs/transition_plots_doc.rst +++ b/docs/transition_plots_doc.rst @@ -1,4 +1,4 @@ -transition_plots +Transition Plots ---------------- .. automodule:: scripts.transition_plots diff --git a/scripts/create_cyclus_input.py b/scripts/create_cyclus_input.py index 3b8c553a..a21373d9 100644 --- a/scripts/create_cyclus_input.py +++ b/scripts/create_cyclus_input.py @@ -1,6 +1,4 @@ import pandas as pd -import sys - import predicting_the_past_import as import_data # module containing functions to build CYCLUS input file diff --git a/scripts/dataframe_analysis.py b/scripts/dataframe_analysis.py index e56cfd02..b53113e1 100644 --- a/scripts/dataframe_analysis.py +++ b/scripts/dataframe_analysis.py @@ -1,5 +1,4 @@ import numpy as np -import pandas as pd def add_year(df): diff --git a/scripts/output_metrics.py b/scripts/output_metrics.py index 6e3a6927..41900c5b 100644 --- a/scripts/output_metrics.py +++ b/scripts/output_metrics.py @@ -49,18 +49,18 @@ def get_table_from_output(db_file, table_name): issues experienced, and only the columns called here were used for later functions. - Parameters - ---------- - db_file: str - filename of database - table_name: str - name of table in the database + Parameters + ---------- + db_file: str + filename of database + table_name: str + name of table in the database - Returns - ------- - table_df: DataFrame - requested table from database - ''' + Returns + ------- + table_df: DataFrame + requested table from database + ''' connect = sqlite3.connect(db_file) if table_name == 'Resources': table_df = pd.read_sql_query( diff --git a/scripts/predicting_the_past_import.py b/scripts/predicting_the_past_import.py index aafe2dd4..5ec45abe 100644 --- a/scripts/predicting_the_past_import.py +++ b/scripts/predicting_the_past_import.py @@ -249,7 +249,7 @@ def import_csv(in_csv, delimit=','): lists. Parameters - ---------- + --------- in_csv: str path and name of input csv file delimit: str @@ -272,7 +272,7 @@ def load_template(in_template): """ Returns a jinja2 template from file. Parameters - ---------- + --------- in_template: str path and name of jinja2 template @@ -290,7 +290,7 @@ def get_composition_fresh(in_list, burnup): using vision_recipes for fresh UOX fuel. Parameters - ---------- + --------- in_list: list list containing vision_recipes burnup: int @@ -322,7 +322,7 @@ def get_composition_spent(in_list, burnup): using vision_recipes for spent nuclear fuel Parameters - ---------- + --------- in_list: list list containing vision_recipes data burnup: int @@ -354,7 +354,7 @@ def write_recipes(fresh_dict, spent_dict, in_template, """ Renders jinja template using fresh and spent fuel composition. Parameters - ---------- + --------- fresh_dict: dict dictionary with key=[isotope], and value=[composition] for fresh UOX @@ -384,7 +384,7 @@ def produce_recipes(in_csv, recipe_template, burnup, out_path): """ Generates commodity composition xml input for cyclus. Parameters - ---------- + --------- in_csv: str path and name of recipe file recipe_template: str @@ -657,7 +657,7 @@ def write_deployment(in_dict, out_path, deployinst_template, located in cyclus_input/reactors. Parameters - ---------- + --------- in_dict: dictionary dictionary with key=[reactor name], and value=[buildtime] out_path: str @@ -738,7 +738,7 @@ def deploy_reactors(in_csv, region, start_year, deployinst_template, in a CYCLUS simulation. Parameters - ---------- + --------- in_csv: str path to pris reactor database region: str diff --git a/scripts/transition_metrics.py b/scripts/transition_metrics.py index 0ff8f3dd..346e8831 100644 --- a/scripts/transition_metrics.py +++ b/scripts/transition_metrics.py @@ -13,13 +13,13 @@ def get_metrics(db_file): ''' Opens database using cymetric and evaluates metrics - Parameters: - ----------- + Parameters + ---------- db_file: str SQLite database from Cyclus - Returns: - -------- + Returns + ------- metrics_evaler: Evaluator object contains all of the metrics of the database ''' @@ -40,15 +40,15 @@ def get_lwr_totals(db_file, non_lwr_prototypes): there are far more LWR prototype names than non-LWR prototype names. - Parameters: - ----------- + Parameters + ---------- db_file: str SQLite database from Cyclus non_lwr_prototypes: list of str names of non LWR prototypes in the simulation - Returns: - -------- + Returns + ------- simulation_data: DataFrame Contains the number of each prototype commissioned and decommissioned at each time step and a column @@ -119,8 +119,8 @@ def get_prototype_totals(db_file, non_lwr_prototypes, prototypes): of zeros is added with the column name reflecting the prototype name. - Parameters: - ----------- + Parameters + ---------- db_file: str name of SQLite database from Cyclus non_lwr_prototypes: list of str @@ -128,8 +128,8 @@ def get_prototype_totals(db_file, non_lwr_prototypes, prototypes): prototypes: list of str list of names of prototypes to be summed together - Returns: - -------- + Returns + ------- prototypes_df : DataFrame enter, exit, and totals for each type of prototype specified. Includes a column totaling all of the @@ -169,13 +169,13 @@ def add_receiver_prototype(db_file): AgentId column renamed to ReceivedId to assist the merge process. The final dataframe is organized by ascending order of Time then TransactionId - Parameters: - ----------- + Parameters + ---------- db_file: str SQLite database from Cyclus - Returns: - -------- + Returns + ------- receiver_prototype: dataframe contains all of the transactions with the prototype name of the receiver included @@ -207,13 +207,13 @@ def add_sender_prototype(db_file): AgentId column renamed to SenderId to assist the merge process. The final dataframe is organized by ascending order of Time then TransactionId - Parameters: - ----------- + Parameters + ---------- db_file: str SQLite database from Cyclus - Returns: - -------- + Returns + ------- sender_prototype: dataframe contains all of the transactions with the prototype name of the receiver included @@ -242,13 +242,13 @@ def get_annual_electricity(db_file): Gets the time dependent annual electricity output of reactors in the silumation - Parameters: - ----------- + Parameters + ---------- db_file: str SQLite database from Cyclus - Returns: - -------- + Returns + ------- electricity_output: DataFrame time dependent electricity output, includes column for year of time step. The energy column @@ -270,13 +270,13 @@ def get_monthly_electricity(db_file): Gets the time dependent monthy electricity output of reactors in the silumation - Parameters: - ----------- + Parameters + ---------- db_file: str SQLite database from Cyclus - Returns: - -------- + Returns + ------- electricity_output: DataFrame time dependent electricity output, includes column for year of time step. The energy column @@ -299,15 +299,15 @@ def get_prototype_energy(db_file, advanced_rx): prototype name by merging the Agents and AnnualElectricityGeneratedByAgent dataframes so that agents can be grouped by prototype name - Parameters: - ----------- + Parameters + ---------- db_file: str SQLite database from Cyclus advanced_rx: str name of advanced reactor prototype - Returns: - -------- + Returns + ------- prototype_energy: dataframe dataframe of the year and the total amount of electricity generated by all agents of the given prototype name. Values @@ -333,15 +333,15 @@ def get_lwr_energy(db_file, advanced_rx): prototype name by merging the Agents and AnnualElectricityGeneratedByAgent dataframes so that agents can be grouped by prototype name - Parameters: - ----------- + Parameters + ---------- db_file: str SQLite database from Cyclus advanced_rx: list of str name(s) of advanced reactor prototype also present in the simulation - Returns: - -------- + Returns + ------- lwr_energy: dataframe dataframe of the year and the total amount of electricity generated by all of the LWRs in the simulation. The energy From 22f091644ca37eb0bcac060ab0bcea0bc49f3793 Mon Sep 17 00:00:00 2001 From: Nathan Ryan Date: Thu, 22 Feb 2024 14:57:04 -0600 Subject: [PATCH 3/7] address pep8 comments --- docs/conf.py | 49 +++++++++++++++++++++++-------------- scripts/output_metrics.py | 3 +-- scripts/transition_plots.py | 18 +++++++++----- 3 files changed, 43 insertions(+), 27 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 3e85cef3..ec5c6da2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -30,23 +30,32 @@ # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = [#'sphinx.ext.autodoc', # generate docs from docstrings - #'sphinx.ext.napoleon', # numpy docstring style - #'m2r2', # allows sphinx to import the readmes from the code - #'sphinx.ext.autosectionlabel', # import autolabel sections - #'sphinx.ext.intersphinx', # make links - "myst_parser", # Adds support for Markedly Structured Text, includes more features - "sphinx.ext.napoleon", # Numpy docstring style - "sphinx.ext.duration", # Represent time durations in a human-readable format - "sphinx.ext.autosectionlabel", # Labels sections - "sphinx.ext.autodoc", # Generate docs from docstrings - "sphinx.ext.autosummary", # Generates summary tables of contents for modules and packages - "sphinx.ext.intersphinx", # Linking to external documentation sites - "sphinx.ext.viewcode", # Adds "View Source" links to docs - "sphinx.ext.mathjax", # Render mathematical expressions written in LaTeX - "sphinx.ext.coverage", # Assessing and visualizing the test coverage - "nbsphinx", # Include Jupyter Notebooks in docs - "sphinxcontrib.mermaid" # Create diagrams in markdown + +# myst_parser adds support for Markedly Structured Text, includes more features +# sphinx.ext.napoleon allows for a google/numpy docstring style +# sphinx.ext.duration represents time durations in a human-readable format +# sphinx.ext.autosectionlabel labels sections +# sphinx.ext.autodoc generates docs from docstrings +# sphinx.ext.autosummary generates summary tables of modules and packages +# sphinx.ext.intersphinx allows for linking to external documentation sites +# sphinx.ext.viewcode adds "View Source" links to docs +# sphinx.ext.mathjax renders mathematical expressions written in LaTeX +# sphinx.ext.coverage assesses and visualizing the test coverage +# nbsphinx includes Jupyter Notebooks in docs +# sphinxcontrib.mermaid create diagrams in markdown + +extensions = ["myst_parser", + "sphinx.ext.napoleon", + "sphinx.ext.duration", + "sphinx.ext.autosectionlabel", + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.intersphinx", + "sphinx.ext.viewcode", + "sphinx.ext.mathjax", + "sphinx.ext.coverage", + "nbsphinx", + "sphinxcontrib.mermaid" ] @@ -69,11 +78,13 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] # List of modules to be mocked up. -autodoc_mock_imports = ['pyne', 'd3ploy','seaborn','xmltodict', 'dataframe_analysis','predicting_the_past_import', 'create_AR_DeployInst'] +autodoc_mock_imports = ['pyne', 'd3ploy', 'seaborn', 'xmltodict', + 'dataframe_analysis', 'predicting_the_past_import', + 'create_AR_DeployInst'] intersphinx_mapping = { 'python': ('https://docs.python.org/3', None), - 'pandas':('https://pandas.pydata.org/docs/', None), + 'pandas': ('https://pandas.pydata.org/docs/', None), 'numpy': ('https://numpy.org/doc/stable/', None), 'astropy': ('https://docs.astropy.org/en/stable/', None), 'cyclus': ('https://fuelcycle.org/', None) diff --git a/scripts/output_metrics.py b/scripts/output_metrics.py index 41900c5b..17492056 100644 --- a/scripts/output_metrics.py +++ b/scripts/output_metrics.py @@ -563,5 +563,4 @@ def run_cyclus(output_sqlite, input_xml): ''' if not os.path.exists(output_sqlite): os.system('cyclus -i ' + input_xml + ' -o ' + output_sqlite + - ' --warn-limit 2') - + ' --warn-limit 2') \ No newline at end of file diff --git a/scripts/transition_plots.py b/scripts/transition_plots.py index b8e92c92..96e6dab5 100644 --- a/scripts/transition_plots.py +++ b/scripts/transition_plots.py @@ -300,15 +300,18 @@ def get_undersupply_timesteps( Demand equation, only used if driving_commod is True. Defaults to '0'. demand_driving : bool, optional - Indicates whether the commodities are demand-driven (True) or supply-driven (False). + Indicates whether the commodities are demand-driven (True) or + supply-driven (False). Defaults to True. Returns ------- dict_dots : dict - Timeseries dictionary with 1 and 0 indicating undersupply at specific time steps. + Timeseries dictionary with 1 and 0 indicating undersupply at specific + time steps. diff_dict_drop : dict - Timeseries dictionary with absolute difference between supply and demand, if supply < demand. + Timeseries dictionary with absolute difference between supply and + demand, if supply < demand. """ if driving_commod: @@ -347,7 +350,8 @@ def plot_all_undersupply( title='', name='hello'): """ - Generates a comparison plot of commodity undersupply for different prediction methods. + Generates a comparison plot of commodity undersupply for different + prediction methods. Parameters ---------- @@ -360,7 +364,8 @@ def plot_all_undersupply( general_sqlite : str Name of the SQLite database without the method name added at the end. demand_driven : bool, optional - Boolean indicating whether the commodities are demand-driven (True) or supply-driven (False). + Boolean indicating whether the commodities are demand-driven (True) or + supply-driven (False). Defaults to True. demand_eq : str, optional Equation for power demand. Defaults to '0'. @@ -524,7 +529,8 @@ def plot_histogram( name, yticks): """ - Plots a histogram comparing undersupplied time steps for different commodities and prediction methods. + Plots a histogram comparing undersupplied time steps for different + commodities and prediction methods. Parameters ---------- From a4372463301d6c85660a9db37c093848ffba6315 Mon Sep 17 00:00:00 2001 From: Nathan Ryan Date: Thu, 22 Feb 2024 15:01:42 -0600 Subject: [PATCH 4/7] second round of pep8 comments --- docs/conf.py | 9 +++++---- scripts/output_metrics.py | 2 +- scripts/transition_plots.py | 3 ++- 3 files changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index ec5c6da2..03671f3b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -56,8 +56,7 @@ "sphinx.ext.coverage", "nbsphinx", "sphinxcontrib.mermaid" - -] + ] # Suffixes that are useable # source_suffix = { @@ -67,7 +66,9 @@ # } # make sure you have a unique autolabelled target -autosectionlabel_prefix_document = True # Sphinx will create explicit targets for all your sections, the name of target has the form {path/to/page}:{title-of-section}. +autosectionlabel_prefix_document = True +# Sphinx will create explicit targets for all your sections, the name of target +# has the form {path/to/page}:{title-of-section}. # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -101,4 +102,4 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['source/_static'] \ No newline at end of file +html_static_path = ['source/_static'] diff --git a/scripts/output_metrics.py b/scripts/output_metrics.py index 17492056..affd0acc 100644 --- a/scripts/output_metrics.py +++ b/scripts/output_metrics.py @@ -563,4 +563,4 @@ def run_cyclus(output_sqlite, input_xml): ''' if not os.path.exists(output_sqlite): os.system('cyclus -i ' + input_xml + ' -o ' + output_sqlite + - ' --warn-limit 2') \ No newline at end of file + ' --warn-limit 2') diff --git a/scripts/transition_plots.py b/scripts/transition_plots.py index 96e6dab5..2985816f 100644 --- a/scripts/transition_plots.py +++ b/scripts/transition_plots.py @@ -294,7 +294,8 @@ def get_undersupply_timesteps( commod : str Name of the commodity. driving_commod : bool, optional - Indicates if the commodity is a driving commodity (True) or not (False). + Indicates if the commodity is a driving commodity (True) + or not (False). Defaults to False. demand_eq : str, optional Demand equation, only used if driving_commod is True. From f8eb7dce21571b81788ac4bf88b442655809559e Mon Sep 17 00:00:00 2001 From: Nathan Ryan Date: Thu, 22 Feb 2024 15:05:04 -0600 Subject: [PATCH 5/7] third round of pep8 comments --- docs/conf.py | 3 +-- scripts/output_metrics.py | 2 +- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 03671f3b..11737b37 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -55,8 +55,7 @@ "sphinx.ext.mathjax", "sphinx.ext.coverage", "nbsphinx", - "sphinxcontrib.mermaid" - ] + "sphinxcontrib.mermaid"] # Suffixes that are useable # source_suffix = { diff --git a/scripts/output_metrics.py b/scripts/output_metrics.py index affd0acc..86e826d4 100644 --- a/scripts/output_metrics.py +++ b/scripts/output_metrics.py @@ -563,4 +563,4 @@ def run_cyclus(output_sqlite, input_xml): ''' if not os.path.exists(output_sqlite): os.system('cyclus -i ' + input_xml + ' -o ' + output_sqlite + - ' --warn-limit 2') + ' --warn-limit 2') From 4d09703448b055cae7b7a02c303bcc6a60aea1d5 Mon Sep 17 00:00:00 2001 From: Nathan Ryan Date: Thu, 22 Feb 2024 15:05:58 -0600 Subject: [PATCH 6/7] indentation fix in output metrics --- scripts/output_metrics.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/output_metrics.py b/scripts/output_metrics.py index 86e826d4..4be07735 100644 --- a/scripts/output_metrics.py +++ b/scripts/output_metrics.py @@ -563,4 +563,4 @@ def run_cyclus(output_sqlite, input_xml): ''' if not os.path.exists(output_sqlite): os.system('cyclus -i ' + input_xml + ' -o ' + output_sqlite + - ' --warn-limit 2') + ' --warn-limit 2') From 11dc92f11a1a84fb455b1e9a14a4e02329848693 Mon Sep 17 00:00:00 2001 From: Nathan Ryan Date: Fri, 23 Feb 2024 09:33:40 -0600 Subject: [PATCH 7/7] add instructions on building the docs to the readme with requirements --- docs/conf.py | 2 +- docs/docs_README.md | 6 ------ docs/index.md | 28 +++++++++++++++++++++++++++- 3 files changed, 28 insertions(+), 8 deletions(-) delete mode 100644 docs/docs_README.md diff --git a/docs/conf.py b/docs/conf.py index 11737b37..3ddf1988 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -87,7 +87,7 @@ 'pandas': ('https://pandas.pydata.org/docs/', None), 'numpy': ('https://numpy.org/doc/stable/', None), 'astropy': ('https://docs.astropy.org/en/stable/', None), - 'cyclus': ('https://fuelcycle.org/', None) + 'cyclus': ('https://fuelcycle.org/', None), } diff --git a/docs/docs_README.md b/docs/docs_README.md deleted file mode 100644 index be1d1e3d..00000000 --- a/docs/docs_README.md +++ /dev/null @@ -1,6 +0,0 @@ - - - -Requirements -============ - m2r2 diff --git a/docs/index.md b/docs/index.md index e376a3a2..0232e4c1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -26,4 +26,30 @@ transition_plots_doc - {ref}`genindex` - {ref}`modindex` -- {ref}`search` \ No newline at end of file +- {ref}`search` + + +# Building the Docs +To compile the documentation, make sure you have all the requirements +installed, then run `make html` from the top level of the repository. + +```{warning} +The docs are still in their nascent stage. If you find a +problem, please open an issue on +[github](https://github.com/arfc/transition-scenarios/issues). +``` + +## Docs Requirements +* sphinx +* myst_parser +* sphinx.ext.napoleon +* sphinx.ext.duration +* sphinx.ext.autosectionlabel +* sphinx.ext.autodoc +* sphinx.ext.autosummary +* sphinx.ext.intersphinx +* sphinx.ext.viewcode +* sphinx.ext.mathjax +* sphinx.ext.coverage +* nbsphinx +* sphinxcontrib.mermaid \ No newline at end of file