docs: restructure ReadTheDocs into tiered guide with flexibility chap…#646
Open
joda9 wants to merge 14 commits into
Open
docs: restructure ReadTheDocs into tiered guide with flexibility chap…#646joda9 wants to merge 14 commits into
joda9 wants to merge 14 commits into
Conversation
…ters Reorganise the documentation by depth (Getting Started → User Guide → Methodology & Physics → Reference) so it is usable for all user levels, and rebuild the flexibility & optimisation documentation from the ground up. - New grouped toctree in index.rst; split usage_details into a task-oriented User Guide (data sources, workflow, data model, time series, components, analysis & results) and retire features_in_detail.rst - Add Methodology pages (power flow, grid reinforcement, complexity reduction) that explain each function and its physics, cross-linked to the AutoAPI ref - Add methodology/flexibility/* : overview, multi-period OPF (pm_optimize, SOC/NC, opf_version 1-4), electromobility, heat pumps, DSM, storage, reactive power and overlying grid - Render the hands-on walkthrough and example notebooks via nbsphinx (nbsphinx_execute=never); switch math to MathJax; set language to "en" - Add an installation page and a slim contributing guide; move legacy/ unmaintained methods (non-linear OPF, curtailment, storage heuristic) to a clearly marked "Experimental & Legacy" section - Fix outdated API cross-references (e.g. mv_line_overload -> mv_line_max_relative_overload), stale labels (features-in-detail) in reinforce_grid.py and edisgo.py, the grid.components namespace, and a copy-paste error in the DSM.p_max docstring - Include the orphaned whatsnew/v0-3-0 entry and describe the doc restructuring in it - Build infra: add nbsphinx/ipython to rtd_requirements.txt and pandoc to .readthedocs.yml Tutorial notebooks: - Translate full_workflow_walkthrough.ipynb fully to English (markdown, prose and code comments) - Make full_workflow_walkthrough.ipynb portable: download the egon-format example grid (ding0_test_network_3) into $EDISGO_DATA_DIR (default ~/.edisgo) instead of hard-coded local paths, and genericise the kernelspec - Fix simple_example.ipynb internal TOC: point links at the real heading slugs and convert citation links to plain text, clearing the 6 nbsphinx "undefined label" warnings Docstrings (feed AutoAPI): - reinforce_measures.separate_lv_grid: document the edisgo_obj and grid params; wrap two over-length log/error strings (ruff E501) - network.heat.HeatPump: expand the class docstring with attribute pointers and clarify the thermal_storage_units_df columns (capacity, efficiency round-trip semantics, state_of_charge_initial)
joda9
force-pushed
the
docs/restructure-readthedocs
branch
from
c0d76b1 to
75db7af
Compare
Follow-up cleanup on the ReadTheDocs restructuring. - Update 18 stale doc links across all tutorial notebooks: old api/*.html -> AutoAPI per-class pages, retired features_in_detail/usage_details/configs -> their new methodology/userguide/reference pages, dead quickstart anchors, and the non-existent draw_plotly ref -> plot_plotly - Normalise heading levels in simple_example.ipynb and plot_example.ipynb (no more h2->h4 skips), clearing the docutils "inconsistent title style" errors - tools.config.get_database_alias_dictionaries: fix the malformed :returns: list that produced a docutils block-quote warning Docs build is clean (only the pre-existing AutoAPI duplicate-object warnings remain; zero docutils errors).
Add explanatory figures to the methodology pages and rework how the power-flow page frames time series. Figures (generated, reproducible via doc/images/methodology_figures.py; matplotlib + numpy, synthetic/illustrative data): - flexibility bands (generic), EV bands and DSM bands — power band + energy corridor - optimise-then-reinforce workflow + reinforcement-cost comparison - SOC relaxation (cone) and the radial branch-flow model - heat pump with thermal storage: shows P_heat = COP * P_el, with E_th on its own axis and a distinct colour so it is not confused with the heat flow - load case vs. feed-in case - spatial complexity reduction: clusters along the grid graph so the reduced grid stays radial and the HV/MV station is preserved Each figure is embedded with a caption in the matching methodology page. Power-flow page (methodology/power_flow.rst): - foreground the main use — running the power flow over real future-scenario time series (set_timeindex + set_time_series_active_power_predefined, e.g. eGon2035) — in a new "Which time series?" section, with worst-case analysis as the quick alternative - reframe "Load case and feed-in case" as a classification of each operating point that selects which limit applies (undervoltage/drop vs overvoltage/rise, with the asymmetric allowed bands), and explicitly distinguish it from worst-case time series
Second critical pass over the restructured docs and every AutoAPI docstring,
plus filling remaining functionality gaps in the prose docs.
Corrections
- results.py: fix copy-paste in pfa_p (q_0 -> q_1) and pfa_q ("Active" ->
"Reactive")
- whatsnew v0.3.0: mark unreleased, repair broken #428 link, correct #346 -> #364
- contributing: linting list flake8 -> Ruff
- costs.grid_expansion_costs: "Attributes" -> "Parameters" docstring header
- use :func: instead of :attr: for module-level functions (voltage_issues,
charging_strategy, _integrate_pv_rooftop)
- installation/data_sources: fix ding0 doc anchor (#ding0-examples -> #examples)
- geopandas_helper.plot: replace TODO-only docstring
New docstrings (feed AutoAPI)
- opf_result_class: OPFResults, LineVariables, HeatStorage, BatteryStorage,
GridSlacks
- components.PotentialChargingParks (+ edisgo_id, grid_connection_capacity)
- config db_table/schema mappings; db.py, geo, electromobility_import,
powermodels_io helpers
Docs
- reference/configs: document config_opf_julia, correct the file count
- methodology/electromobility: add "Grid integration" section explaining
connection sizing via the simultaneity/diversity factor; fix heading level
- methodology/optimization_opf: note per-unit s_base and the SOC-exactness
condition; describe the OPFResults container
- userguide/analysis_results: list the remaining plot methods (plot_mv_grid,
plot_mv_storage_integration, plot_voltage_over_dist[_mv])
- userguide/workflow: mention check_integrity
- userguide/data_sources: clarify oedb/OEP/egon-data naming; mention
import_ding0_grid
- userguide/time_series: real manual-series example; drop stale "planned" note
- determine_grid_connection_capacity: document non-monotonicity (#650)
Style
- wrap a few pre-existing over-length log/error f-strings to satisfy ruff E501
in touched files (electromobility_import, generators_import, components)
- complexity_reduction: fix temporal-reduction module reference — reinforce (reduced_analysis=True) uses tools.temporal_complexity_reduction.get_most_critical_*, not opf.timeseries_reduction; distinguish the OPF step selection (get_steps_curtailment / get_steps_storage) - time_series: document TimeSeries.scale_timeseries - data_model: mention Grid feeder methods (assign_grid_feeder, get_feeder_stats)
Addresses recurring confusion about which charging points get a time series (and how) in the electromobility workflow. - electromobility (charging strategies): state explicitly that only the private use cases (home, work) are shifted by "reduced"/"residual", while public and hpc are always charged "dumb"; "dumb" charges every use case. After apply_charging_strategy every charging point has an active-power series (none left unset), which is what a later power flow / OPF needs. - time_series (predefined): note that charging points need explicit per-use-case profiles via charging_points_ts (there is no oedb source); if omitted, charging points -- including public ones -- are left without a series. Point to apply_charging_strategy as the automatic alternative.
The component types were only discoverable indirectly -- grid components under "the data model", flexibilities under the methodology. Add a dedicated "Components" page to the User Guide that catalogues both, and cross-link it. - new userguide/components_overview.rst: tables of grid components (with their topology DataFrame and component class) and flexibility components (with their container and methodology page) - index: add it to the User Guide toctree after "The data model" - cross-links from "Adding and modifying components" and the flexibility overview to the new page
The illustrative figure overstated the effect (~70% cost reduction). Adjust the "with optimisation" values to ~85% of the baseline so each voltage level shows a more realistic ~15% reduction (LV 142->121, MV/LV 88->75, MV 210->178 k€).
Collaborator
Author
|
Remove this: "or set the environment variable OEP_TOKEN_KH" |
Collaborator
Author
|
Add enhanced reinforcement |
Collaborator
Author
|
Add a section about switches |
Collaborator
Author
|
Add more doc to the Julia side |
joda9
force-pushed
the
docs/restructure-readthedocs
branch
from
459f20e to
3bb4f83
Compare
Sphinx cannot autodoc Julia, and Documenter.jl only builds a separate standalone HTML site. To show the Julia OPF API as a normal page inside the Python documentation — same theme, same left-hand TOC, same search — add a small Sphinx extension that parses the Julia source for docstrings (no Julia runtime, no Gurobi) and writes a MyST-Markdown page that Sphinx renders like any other page. - Add doc/_ext/julia_autodoc.py: on builder-inited it scans edisgo/opf/eDisGo_OPF.jl/src for documented definitions and generates doc/reference/julia_api.md, regenerated on every build so it grows as docstrings are added. It mirrors Julia's own attach rule (skips empty "" placeholders and strings separated from the definition by a blank line) and falls back to a stub if the Julia sources are absent. - Wire it in: add myst_parser + julia_autodoc to conf.py (with dollarmath and colon_fence), add myst-parser to rtd_requirements.txt, add the reference/julia_api entry to the Reference toctree, and gitignore the generated page. - Add docstrings throughout the eDisGo_OPF Julia module so the reference is useful: the three problem-formulation structs (base / SOC / NC), the problem build and solve entry points, the variable, constraint and objective functions (mapped to their OPF formulation equations and opf_version variants), and the I/O and solution helpers. The page now lists 81 documented symbols. Also add a module-level docstring and document the Main.jl driver script (source/REPL only; not part of the generated API page).
joda9
force-pushed
the
docs/restructure-readthedocs
branch
from
3bb4f83 to
8982169
Compare
…tencies Document the optimisation model in depth, cite the master's thesis it is based on, and fix inaccuracies found while reviewing the docs for consistency. - optimization_opf.rst: add a "The optimisation model in detail" section (decision variables, objective, network constraints, flexibility dynamics, multi-period structure) with the Eq. (3.x) numbers, plus a note citing the thesis. Explain that minimising line losses also keeps the SOC relaxation tight, and that batteries use a resistance-based loss model. - flexibility/index.rst: add a "The optimisation model" subsection summarising the model and linking the detailed page and the thesis. - Cite Maike Held, "Netzdienlich optimaler Einsatz von Flexibilitaeten in radialen Verteilnetzen basierend auf einem AC-Lastflussmodell", master's thesis, TU Berlin, 2023, as the reference for the formulation. - data_sources.rst: correct the scenario arguments — import_generators uses generator_scenario (eGon2035/eGon100RE for current grids, nep2035/ego100 for legacy), and set_time_series_active_power_predefined selects sources per component type. - storage.rst: clarify that the OPF uses a resistance-based battery loss model rather than the reference operation's efficiency_store/efficiency_dispatch. - Rename the OEP token environment variable OEP_TOKEN_KH to OEP_TOKEN (edisgo/io/db.py and the data-sources page).
…tions Expand the user guide and methodology docs with three new sections: components_overview.rst — new "Switches" section: - explains switches as MV ring disconnecting points, modelled as a branch in lines_df with bus_open/bus_closed and an open/closed state - documents what they drive: power-flow operating point, ring detection, where MV line reinforcement may act, and plotting - shows the Switch object API (state, branch, bus_open/bus_closed, open()/close()) and how switches survive import, complexity reduction and to_pypsa data_model.rst — new "Relationship to the PyPSA format" section: - eDisGo/PyPSA component mapping table with the differing columns - what eDisGo needs beyond PyPSA (grid hierarchy, geo-coordinates, component typing, flexibility containers) and what to_pypsa derives - guidance for representing a PyPSA grid in eDisGo's ding0-based schema grid_reinforcement.rst — rewrite the enhanced reinforcement paragraph into a dedicated section describing the full fallback strategy: LV-grid separation, per-LV reinforcement with splitting, the MV/MV+MV/LV/LV sequence, and the cost-distorting last resort, including the limitation that those measures underestimate grid-expansion costs. Documented two known code limitations as notes: line r/x are passed to PyPSA in ohms (PyPSA converts to per-unit, not to_pypsa) and a b column exists but is always 0; and MV line reinforcement does not yet insert a switch disconnector at the split point (TODO in reinforce_lines_voltage_issues).
joda9
force-pushed
the
docs/restructure-readthedocs
branch
from
7412ce1 to
f188a5a
Compare
Reference the master's theses underlying the EV charging strategies and spatial complexity reduction, and collect the studies that used eDisGo. - electromobility: add a note citing Helfenbein (2021) on grid-friendly charging strategies, with PDF link and a summary of its findings on the "reduced" and "residual" strategies - complexity_reduction: complete the [SCR] reference to Jahn (2022) with full citation, PDF link, and the clustering modes it developed - index: add a "Publications using eDisGo" section linking the peer-reviewed studies (Büttner 2025, Heider 2024/2023, Semmelmann 2023, Schachler 2022, Pedersen 2021) and the ding0 grid dataset
Cross-checked every factual claim in the reworked documentation against the code and corrected all mismatches. Each change below is justified by the concrete code location it was verified against. == userguide/components.rst == * Remove the invalid `add_ts=False` argument from the add_component example. Reason: EDisGo.add_component has no such parameter (edisgo.py:1488); the kwarg would be forwarded into the component DataFrame and silently create a bogus column. Simply omitting the ts_* arguments is the correct "no time series" case. * Rewrite the aggregate_components description: it aggregates generators resp. loads at a bus (by default all of them, optionally grouped by further columns), not "components of the same type", and never storage units. Reason: edisgo.py:1840-1945 (only generators/loads; default cols=["bus"]). == userguide/components_overview.rst == * Fix the MV line-split direction: the feeder is split at the LV station and reconnected directly to the MV station busbar (not "re-routed to the LV station"). Reason: reinforce_measures.py:507-524 sets the predecessor end to the MV busbar. * Clarify that the split happens at an LV station because a switch disconnector can be operated there, not because one currently sits at the split point. Reason: reinforce_measures.py:464 checks for an LV station, not an existing switch. * Soften the spatial_complexity_reduction claim: switches are carried over but unused/duplicated ones are dropped/merged. Reason: spatial_complexity_reduction.py:1753-1790. == userguide/time_series.rst == * Fix the manual example keyword loads_active_power -> loads_p (the old name raises TypeError) and document the units (MW/Mvar) and index requirement. Reason: set_time_series_manual signature edisgo.py:278-286. * Replace the no-argument set_time_series_active_power_predefined() example with one that passes explicit sources; a bare call sets no series at all. Reason: every setter is guarded by `if ... is not None` (edisgo.py:389-636). * Add the dispatchable-generator mechanism and the oedb / own-DataFrame options for conventional loads that the page omitted. Reason: timeseries.py:1339-1479; edisgo.py:488-530. * State that worst-case analysis also sets reactive power (fixed cos phi) and overwrites prior non-worst-case series, with one MV and one LV step per case. Reason: timeseries.py:492-497, 606-639. * Document the per-component-group reactive-power parametrisation options. Reason: timeseries.py:1540-1599. == userguide/data_model.rst == * Correct the graph description: buses are nodes, lines are edges; transformers are edges only in to_graph(), and absent from the per-grid graphs. Reason: networkx_helper.py:47-71; grids.py:99. * Fix the "b is always 0" claim: b is computed from the cable capacitance whenever a line is added/changed and is exported to PyPSA; only g is missing. Reason: tools.py:121-140; topology.py:1445; pypsa_io.py:119. * Map only transformers_df to PyPSA Transformer; transformers_hvmv_df is not exported and only defines the slack bus. Reason: pypsa_io.py:80, 121-145. * Add the source_id column to the generator extra-columns list (topology.py:60-68); qualify which DataFrames grid objects expose and that a grid's transformers_df returns the transformers to the overlying level (grids.py:231-559); state that the switch state is permanently encoded in lines_df rather than resolved "before conversion" (components.py:727-757); and that transformer pu values are taken over from ding0/equipment data, not computed by to_pypsa (ding0_import.py:127-135). == userguide/analysis_results.rst == * Correct the analyze() description: it writes power-flow results; the identification of overloading/voltage problems happens in reinforce() (check_tech_constraints). Reason: edisgo.py:1037-1245. * Fix plot_plotly/plot_dash: these are module functions in edisgo.tools.plots, not EDisGo methods. Reason: plots.py:907, 2330. * Separate save_edisgo_to_json out of the "save the whole object" sentence: it exports PowerModels network data and cannot be reloaded as an EDisGo object. Reason: edisgo.py:3283-3295. * Add units (p.u./MVA/kA/MW/Mvar) and the pfa_p/pfa_q attributes; correct equipment_changes (added/changed/removed) and grid_expansion_costs (per component, kEUR); fix unresolved_issues wording; show that copy_grid=True returns the costs in the returned Results, not in edisgo.results; note plot_voltage_over_dist_mv needs a second object. Reason: results.py:105-583; edisgo.py:1281-1386, 2636-2852. == userguide/data_sources.rst == * Fix the custom-DB example: engine(..., ssh=True) (ssh=False ignores the YAML and connects to the OEP); YAML keys need a leading "--"; the SSH tunnel is mandatory for this path. Reason: db.py:92-248. * State that legacy_ding0_grids defaults to True and must be set False for current grids; add transformers_hvmv.csv / storage_units.csv (and the topology/ subfolder) to the ding0 file list. Reason: ding0_import.py:28, 124-133. * Note that import_electromobility requires an explicit engine for data_source="oedb"; document the directory import path and the pinned SimBEV/TracBEV commit versions. Reason: edisgo.py:1947-2073; electromobility_import.py:164. == userguide/workflow.rst == * Reword the import_generators step (adopt a future-scenario park; skip to keep the status-quo park) — all ding0 grids ship generators. Reason: edisgo.py:965-1024. * Replace the "load series before charging strategy" rule: apply_charging_strategy needs import_electromobility, which it itself feeds; the TimeSeries getters never return None. Reason: charging_strategies.py:62-140; timeseries.py:112-117. * Fix three error-table rows: the impossible TypeError symptom, the heat-pump import default (all three technologies imported), and the charging-strategy precondition. Reason: heat_pump_import.py:347-369; charging_strategies.py:62-140. == quickstart.rst == * Clarify the test grid ships with the repository (not a pip install) and point to ding0_test_network_1 as the smallest grid. Reason: setup.py package_data. * Note that generator scenario names depend on the grid format (nep2035/ego100 for legacy, eGon2035/eGon100RE + engine for current). Reason: edisgo.py:965-1024. == installation.rst == * Replace "Python 3.9 or higher" with the actually tested range (3.10-3.12; conda env pins <=3.11; docs built with 3.11). Reason: env yml files, CI workflow, .readthedocs. * Add Julia 1.6 compat and Ipopt (needed for method="nc"/warm_start) to the OPF prerequisites; Gurobi alone only covers the default SOC method. Reason: eDisGo_OPF.jl/Project.toml; edisgo.py:924-928. == methodology/power_flow.rst == * Correct the load/feed-in case classification: it is network-wide (residual at the HV/MV substation), includes storage discharge, and a zero residual is the load case. Reason: timeseries.py:1835-1868. * Add the analyze() options the page omitted: mode (mv/mvlv/lv with the aggregation side) and the troubleshooting parameters (lpf, iteration, scale_timeseries, raise_not_converged). Reason: edisgo.py:1026-1213. == methodology/complexity_reduction.rst == * Note that aggregate_to_main_feeder / equidistant_nodes only work with cluster_area="main_feeder". Reason: spatial_complexity_reduction.py:386-846. * Fix the OPF step-selection: get_steps_* select/expand critical steps, while get_linked_steps builds the representative clusters; add the default cost-weighting. Reason: timeseries_reduction.py:56-149; temporal_complexity_reduction.py:859. * Broaden reduce_memory: it also downcasts heat-pump and overlying-grid data (float32). Reason: edisgo.py:3361-3412. == methodology/flexibility/electromobility.rst == * Correct the diversity-factor threshold (full connection below 0.3 MW, not just "small parks") and add the non-monotonic-capacity caveat. Reason: electromobility_import.py:1136-1184. * Clarify that the "residual" strategy uses the network-wide residual load, not the MV grid's. Reason: charging_strategies.py:254; timeseries.py:1818-1839. == methodology/flexibility/heat_pumps.rst == * Add the thermal-storage efficiency to the OPF energy-balance equation and mention the per-hour standing-loss factor. Reason: heat.py:130-133; constraint.jl:56. == methodology/flexibility/reactive_power.rst == * Document the per-component-group parametrisation (default / DataFrame / None) that the page presented only as the config-driven default. Reason: timeseries.py:1540-1599; edisgo.py:654-665. == methodology/flexibility/overlying_grid.rst == * Add the central power-to-heat / district-heating requirement attributes; state that distribute_overlying_grid_requirements returns a new EDisGo object and uses a per-flexibility distribution key; fix "central storage" -> aggregate storage units. Reason: overlying_grid.py:52-96, 279-447. == methodology/flexibility/optimization_opf.rst == * Correct the warm-start description: it runs only when the SOC solution is already tight (it does not rescue non-tight solutions); non-tight cases are written to a JSON file. Reason: Main.jl:81-101. * Note the silent fallback of versions 3/4 to version 2 when no overlying-grid data is present. Reason: powermodels_io.py:206-212. * Flag the save_heat_storage/save_slack_gen/save_slacks parameters as currently non-functional (declared but not forwarded) and document the working silence_moi. Reason: edisgo.py:886-948; powermodels_io.py:233-238. == reference/configs.rst == * Describe the real config-override mechanisms (~/.edisgo/config, config_path, in-memory edisgo.config) and that config_system.cfg also holds the equipment-file mapping and network parameters (frequency). Reason: config.py:80-82, 562-565; config_system.cfg. * Correct the config_db_tables summary (data source model_draft/versioned + version + table-name mapping) and the config_grid summary (geo SRID, connection/buffer params, max voltage deviations). Reason: config_db_tables_default.cfg; config_grid_default.cfg. * Complete the config_grid_expansion section list (standard equipment, n-1 load factors, cost sections). Reason: config_grid_expansion_default.cfg. == reference/equipment.rst == * Describe the per-km impedance columns (U_n, R/L/C_per_km) and transformer columns (u_kr, P_k) with their units, which the prose previously omitted. Reason: equipment CSV headers verified directly.
Cross-checked the docstrings against the actual code (the autoapi-rendered API
reference must match the implementation) and corrected all mismatches. Each
change is justified by the code location it was verified against.
== edisgo.py ==
* import_dsm: described p_min and p_max BOTH as "load increase". p_min is a load
*decrease*. Now: decrease (p_min) / increase (p_max) / preponing (e_min) /
postponing (e_max). Also dropped the stray `edisgo_object` entry that is not a
parameter of this bound method. Reason: network/dsm.py:34-144 + signature 2346.
* apply_charging_strategy: "'public' charging will always be 'dumb'" omitted 'hpc'.
Both public AND hpc are always dumb. Reason: flex_opt/charging_strategies.py:223,289.
== network/topology.py, network/grids.py, tools/networkx_helper.py ==
* All three graph docstrings claimed "buses and transformers are represented by
nodes". Transformers are EDGES (length 0) in to_graph(), and absent from the
per-grid graph (translate_df_to_graph is called without transformers in grids.py).
Corrected all three (incl. the helper's parameter description).
Reason: tools/networkx_helper.py:47-71; grids.py:99.
== network/components.py ==
* PotentialChargingParks.charging_processes_df: use-case values documented as
"private or public"; the real values are "hpc"/"home"/"public"/"work".
Reason: electromobility.py:113-114; components.py use_case property.
== network/timeseries.py ==
* set_worst_case: charging-point config keys documented as 'mv_load-in_case_cp_*'
etc.; the real token is 'load_case' ('mv_load_case_cp_*').
Reason: timeseries.py:1000 (f"{voltage_level}_{case}_cp_{s}"); config_timeseries.
* timesteps_load_feedin_case: residual-load description omitted the storage term and
wrongly localized it "at HV/MV substation". It is load - generation - storage over
the whole network; corrected, and the zero case is the load case.
Reason: timeseries.py:1835-1868.
== network/results.py ==
* to_csv: pfa_slack documented as saved to 'pfa_slack.csv'; the actual file is
'slack_results.csv'. Reason: results.py:49 mapping + _save_power_flow_results.
== network/electromobility.py ==
* to_csv: simbev_config_df documented as saved to 'simbev_config.csv'; the actual
file is 'metadata_simbev_run.csv'. Reason: electromobility.py:1043-1053 mapping.
== flex_opt/reinforce_grid.py ==
* enhanced_reinforce_grid: claimed BOTH cost-disturbing measures are "not included
in the costs". The standard-line replacement IS written to equipment_changes and
DOES enter the costs; only the station aggregation leaves no costed trace.
Reason: reinforce_grid.py:1019-1025 + costs.py:117-215.
== flex_opt/costs.py ==
* grid_expansion_costs: documented return column 'line_length' (actual column is
'length') and a non-existent 'mv_feeder' column (only present in the empty
fallback). Corrected the name; removed the mv_feeder entry.
Reason: costs.py:206-208, 226.
== io/db.py ==
* engine: the `ssh` behaviour was documented INVERTED — "False = local database".
In fact ssh=False connects to the remote Open Energy Platform, ssh=True opens an
ssh tunnel to a local egon-data database. Corrected. credentials(): "local
database" -> egon-data database. Reason: db.py:192-248.
== io/generators_import.py ==
* oedb_legacy: generator_scenario options listed only 'nep2035'/'ego100'; the
mapping also accepts 'status_quo' (alias 'sq'), case-insensitive.
Reason: generators_import.py:317-323.
== io/dsm_import.py ==
* oedb / get_profile_cts: parameter documented as `edisgo_object`; the signature is
`edisgo_obj`. Same p_min/p_max "load increase" error as in edisgo.py, corrected.
get_profile_cts return columns documented as "site ID as integer"; they are CTS
load names. Reason: dsm_import.py:35,214,286-296.
== io/powermodels_io.py ==
* from_powermodels: pm_results path format clarified — a given file is read via
json.loads(json.load(f)), i.e. it must contain a JSON-encoded string, not a plain
JSON object. Reason: powermodels_io.py:256-264.
== tools/tools.py ==
* calculate_voltage_diff_pu_per_line_from_type: `cable_names` described as
"Resistance per kilometer" (it is the cable type name(s) used as an index into the
equipment data); `component_type` described as optional with a non-existent
reactive_power_mode/power_factor interaction (it is a required parameter).
Reason: tools.py:260, 305, 308.
== tools/spatial_complexity_reduction.py ==
* make_busmap_grid: parameter type written as the literal `True` instead of `bool`.
Reason: signature line 391 (preserve_trafo_bus_coordinates: bool = True).
== tools/plots.py ==
* mv_grid_topology: removed the documented `line_load` parameter, which does not
exist in the signature; line loading is computed internally from
edisgo_obj.results. plot_plotly: the node_color=None bullet was a copy-paste from
line_color ("Line color is black") — nodes fall back to grey.
Reason: plots.py:232-251, 579-584, 1381.
Incidental: ruff-format wrapped two pre-existing overlong lines in
network/timeseries.py (to_csv/from_csv) when run via pre-commit; included here.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Restructure ReadTheDocs into a tiered guide with flexibility chapters
Summary
Reorganises the documentation from a flat set of long pages into a tiered structure (User Guide → Methodology → Reference → Tutorials), and adds dedicated chapters for the individual flexibility options. The old monolithic pages (
usage_details.rst,features_in_detail.rst,quickstart.rst, …) are split into focused, navigable topics.What changed
New structure
workflow,components,data_model,data_sources,time_series,analysis_resultspower_flow,grid_reinforcement,complexity_reduction, plus aflexibility/section (DSM, e-mobility, heat pumps, storage, reactive power, overlying grid, OPF optimisation)configs,definitions_and_units,equipmentdoc/tutorials/(simple_example,plot_example,electromobility_example, and the newfull_workflow_walkthrough)doc/legacy/Other
doc/conf.py,.readthedocs.yml,rtd_requirements.txtedisgo.py,reinforce_grid.py,dsm.py.license-header.txt~4.8k insertions / ~1.8k deletions across 42 files; no functional code changes.
doc/tutorials/full_workflow_walkthrough.ipynbto English — it still contains German comments/markdown (~17 occurrences, e.g. "zentrale Parameter", "Busse", "Finale Ausbaukosten gesamt").pooch-based fetching:/home/gurobi/.ding0/2024-07-25T17.../ding0_grids/storage/JoDa/hands_on_session/results/storage/JoDa/hands_on_session/.venv311/bin/pythonHow to review
Build the docs locally and check navigation/cross-references: