-
- Read the Docs
- v: ${config.versions.current.slug}
-
-
-
- ${renderLanguages(config)}
- ${renderVersions(config)}
- ${renderDownloads(config)}
-
- On Read the Docs
-
- Project Home
-
-
- Builds
-
-
- Downloads
-
-
-
- Search
-
-
-
-
-
-
- Hosted by Read the Docs
-
-
-
- `;
-
- // Inject the generated flyout into the body HTML element.
- document.body.insertAdjacentHTML("beforeend", flyout);
-
- // Trigger the Read the Docs Addons Search modal when clicking on the "Search docs" input from inside the flyout.
- document
- .querySelector("#flyout-search-form")
- .addEventListener("focusin", () => {
- const event = new CustomEvent("readthedocs-search-show");
- document.dispatchEvent(event);
- });
- })
-}
-
-if (themeLanguageSelector || themeVersionSelector) {
- function onSelectorSwitch(event) {
- const option = event.target.selectedIndex;
- const item = event.target.options[option];
- window.location.href = item.dataset.url;
- }
-
- document.addEventListener("readthedocs-addons-data-ready", function (event) {
- const config = event.detail.data();
-
- const versionSwitch = document.querySelector(
- "div.switch-menus > div.version-switch",
- );
- if (themeVersionSelector) {
- let versions = config.versions.active;
- if (config.versions.current.hidden || config.versions.current.type === "external") {
- versions.unshift(config.versions.current);
- }
- const versionSelect = `
-
- ${versions
- .map(
- (version) => `
-
- ${version.slug}
- `,
- )
- .join("\n")}
-
- `;
-
- versionSwitch.innerHTML = versionSelect;
- versionSwitch.firstElementChild.addEventListener("change", onSelectorSwitch);
- }
-
- const languageSwitch = document.querySelector(
- "div.switch-menus > div.language-switch",
- );
-
- if (themeLanguageSelector) {
- if (config.projects.translations.length) {
- // Add the current language to the options on the selector
- let languages = config.projects.translations.concat(
- config.projects.current,
- );
- languages = languages.sort((a, b) =>
- a.language.name.localeCompare(b.language.name),
- );
-
- const languageSelect = `
-
- ${languages
- .map(
- (language) => `
-
- ${language.language.name}
- `,
- )
- .join("\n")}
-
- `;
-
- languageSwitch.innerHTML = languageSelect;
- languageSwitch.firstElementChild.addEventListener("change", onSelectorSwitch);
- }
- else {
- languageSwitch.remove();
- }
- }
- });
-}
-
-document.addEventListener("readthedocs-addons-data-ready", function (event) {
- // Trigger the Read the Docs Addons Search modal when clicking on "Search docs" input from the topnav.
- document
- .querySelector("[role='search'] input")
- .addEventListener("focusin", () => {
- const event = new CustomEvent("readthedocs-search-show");
- document.dispatchEvent(event);
- });
-});
\ No newline at end of file
diff --git a/docs/_build/html/_static/language_data.js b/docs/_build/html/_static/language_data.js
deleted file mode 100644
index 5776786..0000000
--- a/docs/_build/html/_static/language_data.js
+++ /dev/null
@@ -1,13 +0,0 @@
-/*
- * This script contains the language-specific data used by searchtools.js,
- * namely the set of stopwords, stemmer, scorer and splitter.
- */
-
-const stopwords = new Set(["a", "about", "above", "after", "again", "against", "all", "am", "an", "and", "any", "are", "aren't", "as", "at", "be", "because", "been", "before", "being", "below", "between", "both", "but", "by", "can't", "cannot", "could", "couldn't", "did", "didn't", "do", "does", "doesn't", "doing", "don't", "down", "during", "each", "few", "for", "from", "further", "had", "hadn't", "has", "hasn't", "have", "haven't", "having", "he", "he'd", "he'll", "he's", "her", "here", "here's", "hers", "herself", "him", "himself", "his", "how", "how's", "i", "i'd", "i'll", "i'm", "i've", "if", "in", "into", "is", "isn't", "it", "it's", "its", "itself", "let's", "me", "more", "most", "mustn't", "my", "myself", "no", "nor", "not", "of", "off", "on", "once", "only", "or", "other", "ought", "our", "ours", "ourselves", "out", "over", "own", "same", "shan't", "she", "she'd", "she'll", "she's", "should", "shouldn't", "so", "some", "such", "than", "that", "that's", "the", "their", "theirs", "them", "themselves", "then", "there", "there's", "these", "they", "they'd", "they'll", "they're", "they've", "this", "those", "through", "to", "too", "under", "until", "up", "very", "was", "wasn't", "we", "we'd", "we'll", "we're", "we've", "were", "weren't", "what", "what's", "when", "when's", "where", "where's", "which", "while", "who", "who's", "whom", "why", "why's", "with", "won't", "would", "wouldn't", "you", "you'd", "you'll", "you're", "you've", "your", "yours", "yourself", "yourselves"]);
-window.stopwords = stopwords; // Export to global scope
-
-
-/* Non-minified versions are copied as separate JavaScript files, if available */
-BaseStemmer=function(){this.current="",this.cursor=0,this.limit=0,this.limit_backward=0,this.bra=0,this.ket=0,this.setCurrent=function(t){this.current=t,this.cursor=0,this.limit=this.current.length,this.limit_backward=0,this.bra=this.cursor,this.ket=this.limit},this.getCurrent=function(){return this.current},this.copy_from=function(t){this.current=t.current,this.cursor=t.cursor,this.limit=t.limit,this.limit_backward=t.limit_backward,this.bra=t.bra,this.ket=t.ket},this.in_grouping=function(t,r,i){return!(this.cursor>=this.limit||i<(i=this.current.charCodeAt(this.cursor))||i
>>3]&1<<(7&i))||(this.cursor++,0))},this.go_in_grouping=function(t,r,i){for(;this.cursor>>3]&1<<(7&s)))return!0;this.cursor++}return!1},this.in_grouping_b=function(t,r,i){return!(this.cursor<=this.limit_backward||i<(i=this.current.charCodeAt(this.cursor-1))||i>>3]&1<<(7&i))||(this.cursor--,0))},this.go_in_grouping_b=function(t,r,i){for(;this.cursor>this.limit_backward;){var s=this.current.charCodeAt(this.cursor-1);if(i>>3]&1<<(7&s)))return!0;this.cursor--}return!1},this.out_grouping=function(t,r,i){return!(this.cursor>=this.limit)&&(i<(i=this.current.charCodeAt(this.cursor))||i>>3]&1<<(7&i)))&&(this.cursor++,!0)},this.go_out_grouping=function(t,r,i){for(;this.cursor>>3]&1<<(7&s)))return!0;this.cursor++}return!1},this.out_grouping_b=function(t,r,i){return!(this.cursor<=this.limit_backward)&&(i<(i=this.current.charCodeAt(this.cursor-1))||i>>3]&1<<(7&i)))&&(this.cursor--,!0)},this.go_out_grouping_b=function(t,r,i){for(;this.cursor>this.limit_backward;){var s=this.current.charCodeAt(this.cursor-1);if(s<=i&&r<=s&&0!=(t[(s-=r)>>>3]&1<<(7&s)))return!0;this.cursor--}return!1},this.eq_s=function(t){return!(this.limit-this.cursor>>1),o=0,a=e=(l=t[r])[0].length){if(this.cursor=s+l[0].length,l.length<4)return l[2];var g=l[3](this);if(this.cursor=s+l[0].length,g)return l[2]}}while(0<=(r=l[1]));return 0},this.find_among_b=function(t){for(var r=0,i=t.length,s=this.cursor,h=this.limit_backward,e=0,n=0,c=!1;;){for(var u,o=r+(i-r>>1),a=0,l=e=(u=t[r])[0].length){if(this.cursor=s-u[0].length,u.length<4)return u[2];var g=u[3](this);if(this.cursor=s-u[0].length,g)return u[2]}}while(0<=(r=u[1]));return 0},this.replace_s=function(t,r,i){var s=i.length-(r-t);return this.current=this.current.slice(0,t)+i+this.current.slice(r),this.limit+=s,this.cursor>=r?this.cursor+=s:this.cursor>t&&(this.cursor=t),s},this.slice_check=function(){return!(this.bra<0||this.bra>this.ket||this.ket>this.limit||this.limit>this.current.length)},this.slice_from=function(t){var r=!1;return this.slice_check()&&(this.replace_s(this.bra,this.ket,t),r=!0),r},this.slice_del=function(){return this.slice_from("")},this.insert=function(t,r,i){r=this.replace_s(t,r,i);t<=this.bra&&(this.bra+=r),t<=this.ket&&(this.ket+=r)},this.slice_to=function(){var t="";return t=this.slice_check()?this.current.slice(this.bra,this.ket):t},this.assign_to=function(){return this.current.slice(0,this.limit)}};
-var EnglishStemmer=function(){var a=new BaseStemmer,c=[["arsen",-1,-1],["commun",-1,-1],["emerg",-1,-1],["gener",-1,-1],["later",-1,-1],["organ",-1,-1],["past",-1,-1],["univers",-1,-1]],o=[["'",-1,1],["'s'",0,1],["'s",-1,1]],u=[["ied",-1,2],["s",-1,3],["ies",1,2],["sses",1,1],["ss",1,-1],["us",1,-1]],t=[["succ",-1,1],["proc",-1,1],["exc",-1,1]],l=[["even",-1,2],["cann",-1,2],["inn",-1,2],["earr",-1,2],["herr",-1,2],["out",-1,2],["y",-1,1]],n=[["",-1,-1],["ed",0,2],["eed",1,1],["ing",0,3],["edly",0,2],["eedly",4,1],["ingly",0,2]],f=[["",-1,3],["bb",0,2],["dd",0,2],["ff",0,2],["gg",0,2],["bl",0,1],["mm",0,2],["nn",0,2],["pp",0,2],["rr",0,2],["at",0,1],["tt",0,2],["iz",0,1]],_=[["anci",-1,3],["enci",-1,2],["ogi",-1,14],["li",-1,16],["bli",3,12],["abli",4,4],["alli",3,8],["fulli",3,9],["lessli",3,15],["ousli",3,10],["entli",3,5],["aliti",-1,8],["biliti",-1,12],["iviti",-1,11],["tional",-1,1],["ational",14,7],["alism",-1,8],["ation",-1,7],["ization",17,6],["izer",-1,6],["ator",-1,7],["iveness",-1,11],["fulness",-1,9],["ousness",-1,10],["ogist",-1,13]],m=[["icate",-1,4],["ative",-1,6],["alize",-1,3],["iciti",-1,4],["ical",-1,4],["tional",-1,1],["ational",5,2],["ful",-1,5],["ness",-1,5]],b=[["ic",-1,1],["ance",-1,1],["ence",-1,1],["able",-1,1],["ible",-1,1],["ate",-1,1],["ive",-1,1],["ize",-1,1],["iti",-1,1],["al",-1,1],["ism",-1,1],["ion",-1,2],["er",-1,1],["ous",-1,1],["ant",-1,1],["ent",-1,1],["ment",15,1],["ement",16,1]],k=[["e",-1,1],["l",-1,2]],g=[["andes",-1,-1],["atlas",-1,-1],["bias",-1,-1],["cosmos",-1,-1],["early",-1,5],["gently",-1,3],["howe",-1,-1],["idly",-1,2],["news",-1,-1],["only",-1,6],["singly",-1,7],["skies",-1,1],["sky",-1,-1],["ugly",-1,4]],d=[17,64],v=[17,65,16,1],i=[1,17,65,208,1],w=[55,141,2],p=!1,y=0,h=0;function q(){var r=a.limit-a.cursor;return!!(a.out_grouping_b(i,89,121)&&a.in_grouping_b(v,97,121)&&a.out_grouping_b(v,97,121)||(a.cursor=a.limit-r,a.out_grouping_b(v,97,121)&&a.in_grouping_b(v,97,121)&&!(a.cursor>a.limit_backward))||(a.cursor=a.limit-r,a.eq_s_b("past")))}function z(){return h<=a.cursor}function Y(){return y<=a.cursor}this.stem=function(){var r=a.cursor;if(!(()=>{var r;if(a.bra=a.cursor,0!=(r=a.find_among(g))&&(a.ket=a.cursor,!(a.cursora.limit)a.cursor=i;else{a.cursor=e,a.cursor=r,(()=>{p=!1;var r=a.cursor;if(a.bra=a.cursor,!a.eq_s("'")||(a.ket=a.cursor,a.slice_del())){a.cursor=r;r=a.cursor;if(a.bra=a.cursor,a.eq_s("y")){if(a.ket=a.cursor,!a.slice_from("Y"))return;p=!0}a.cursor=r;for(r=a.cursor;;){var i=a.cursor;r:{for(;;){var e=a.cursor;if(a.in_grouping(v,97,121)&&(a.bra=a.cursor,a.eq_s("y"))){a.ket=a.cursor,a.cursor=e;break}if(a.cursor=e,a.cursor>=a.limit)break r;a.cursor++}if(!a.slice_from("Y"))return;p=!0;continue}a.cursor=i;break}a.cursor=r}})(),h=a.limit,y=a.limit;i=a.cursor;r:{var s=a.cursor;if(0==a.find_among(c)){if(a.cursor=s,!a.go_out_grouping(v,97,121))break r;if(a.cursor++,!a.go_in_grouping(v,97,121))break r;a.cursor++}h=a.cursor,a.go_out_grouping(v,97,121)&&(a.cursor++,a.go_in_grouping(v,97,121))&&(a.cursor++,y=a.cursor)}a.cursor=i,a.limit_backward=a.cursor,a.cursor=a.limit;var e=a.limit-a.cursor,r=((()=>{var r=a.limit-a.cursor;if(a.ket=a.cursor,0==a.find_among_b(o))a.cursor=a.limit-r;else if(a.bra=a.cursor,!a.slice_del())return;if(a.ket=a.cursor,0!=(r=a.find_among_b(u)))switch(a.bra=a.cursor,r){case 1:if(a.slice_from("ss"))break;return;case 2:r:{var i=a.limit-a.cursor,e=a.cursor-2;if(!(e{a.ket=a.cursor,o=a.find_among_b(n),a.bra=a.cursor;r:{var r=a.limit-a.cursor;i:{switch(o){case 1:var i=a.limit-a.cursor;e:{var e=a.limit-a.cursor;if(0==a.find_among_b(t)||a.cursor>a.limit_backward){if(a.cursor=a.limit-e,!z())break e;if(!a.slice_from("ee"))return}}a.cursor=a.limit-i;break;case 2:break i;case 3:if(0==(o=a.find_among_b(l)))break i;switch(o){case 1:var s=a.limit-a.cursor;if(!a.out_grouping_b(v,97,121))break i;if(a.cursor>a.limit_backward)break i;if(a.cursor=a.limit-s,a.bra=a.cursor,a.slice_from("ie"))break;return;case 2:if(a.cursor>a.limit_backward)break i}}break r}a.cursor=a.limit-r;var c=a.limit-a.cursor;if(!a.go_out_grouping_b(v,97,121))return;if(a.cursor--,a.cursor=a.limit-c,!a.slice_del())return;a.ket=a.cursor,a.bra=a.cursor;var o,c=a.limit-a.cursor;switch(o=a.find_among_b(f)){case 1:return a.slice_from("e");case 2:var u=a.limit-a.cursor;if(a.in_grouping_b(d,97,111)&&!(a.cursor>a.limit_backward))return;a.cursor=a.limit-u;break;case 3:return a.cursor!=h||(u=a.limit-a.cursor,q()&&(a.cursor=a.limit-u,a.slice_from("e")))}if(a.cursor=a.limit-c,a.ket=a.cursor,a.cursor<=a.limit_backward)return;if(a.cursor--,a.bra=a.cursor,!a.slice_del())return}})(),a.cursor=a.limit-r,a.limit-a.cursor),r=(a.ket=a.cursor,e=a.limit-a.cursor,(a.eq_s_b("y")||(a.cursor=a.limit-e,a.eq_s_b("Y")))&&(a.bra=a.cursor,a.out_grouping_b(v,97,121))&&a.cursor>a.limit_backward&&a.slice_from("i"),a.cursor=a.limit-i,a.limit-a.cursor),e=((()=>{var r;if(a.ket=a.cursor,0!=(r=a.find_among_b(_))&&(a.bra=a.cursor,z()))switch(r){case 1:if(a.slice_from("tion"))break;return;case 2:if(a.slice_from("ence"))break;return;case 3:if(a.slice_from("ance"))break;return;case 4:if(a.slice_from("able"))break;return;case 5:if(a.slice_from("ent"))break;return;case 6:if(a.slice_from("ize"))break;return;case 7:if(a.slice_from("ate"))break;return;case 8:if(a.slice_from("al"))break;return;case 9:if(a.slice_from("ful"))break;return;case 10:if(a.slice_from("ous"))break;return;case 11:if(a.slice_from("ive"))break;return;case 12:if(a.slice_from("ble"))break;return;case 13:if(a.slice_from("og"))break;return;case 14:if(!a.eq_s_b("l"))return;if(a.slice_from("og"))break;return;case 15:if(a.slice_from("less"))break;return;case 16:if(!a.in_grouping_b(w,99,116))return;if(a.slice_del())break}})(),a.cursor=a.limit-r,a.limit-a.cursor),i=((()=>{var r;if(a.ket=a.cursor,0!=(r=a.find_among_b(m))&&(a.bra=a.cursor,z()))switch(r){case 1:if(a.slice_from("tion"))break;return;case 2:if(a.slice_from("ate"))break;return;case 3:if(a.slice_from("al"))break;return;case 4:if(a.slice_from("ic"))break;return;case 5:if(a.slice_del())break;return;case 6:if(!Y())return;if(a.slice_del())break}})(),a.cursor=a.limit-e,a.limit-a.cursor),r=((()=>{var r;if(a.ket=a.cursor,0!=(r=a.find_among_b(b))&&(a.bra=a.cursor,Y()))switch(r){case 1:if(a.slice_del())break;return;case 2:var i=a.limit-a.cursor;if(!a.eq_s_b("s")&&(a.cursor=a.limit-i,!a.eq_s_b("t")))return;if(a.slice_del())break}})(),a.cursor=a.limit-i,a.limit-a.cursor),e=((()=>{var r;if(a.ket=a.cursor,0!=(r=a.find_among_b(k)))switch(a.bra=a.cursor,r){case 1:if(!Y()){if(!z())return;var i=a.limit-a.cursor;if(q())return;a.cursor=a.limit-i}if(a.slice_del())break;return;case 2:if(!Y())return;if(!a.eq_s_b("l"))return;if(a.slice_del())break}})(),a.cursor=a.limit-r,a.cursor=a.limit_backward,a.cursor);(()=>{if(p)for(;;){var r=a.cursor;r:{for(;;){var i=a.cursor;if(a.bra=a.cursor,a.eq_s("Y")){a.ket=a.cursor,a.cursor=i;break}if(a.cursor=i,a.cursor>=a.limit)break r;a.cursor++}if(a.slice_from("y"))continue;return}a.cursor=r;break}})(),a.cursor=e}}return!0},this.stemWord=function(r){return a.setCurrent(r),this.stem(),a.getCurrent()}};
-window.Stemmer = EnglishStemmer;
diff --git a/docs/_build/html/_static/minus.png b/docs/_build/html/_static/minus.png
deleted file mode 100644
index d96755f..0000000
Binary files a/docs/_build/html/_static/minus.png and /dev/null differ
diff --git a/docs/_build/html/_static/plus.png b/docs/_build/html/_static/plus.png
deleted file mode 100644
index 7107cec..0000000
Binary files a/docs/_build/html/_static/plus.png and /dev/null differ
diff --git a/docs/_build/html/_static/pygments.css b/docs/_build/html/_static/pygments.css
deleted file mode 100644
index 6f8b210..0000000
--- a/docs/_build/html/_static/pygments.css
+++ /dev/null
@@ -1,75 +0,0 @@
-pre { line-height: 125%; }
-td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }
-span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }
-td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
-span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
-.highlight .hll { background-color: #ffffcc }
-.highlight { background: #f8f8f8; }
-.highlight .c { color: #3D7B7B; font-style: italic } /* Comment */
-.highlight .err { border: 1px solid #F00 } /* Error */
-.highlight .k { color: #008000; font-weight: bold } /* Keyword */
-.highlight .o { color: #666 } /* Operator */
-.highlight .ch { color: #3D7B7B; font-style: italic } /* Comment.Hashbang */
-.highlight .cm { color: #3D7B7B; font-style: italic } /* Comment.Multiline */
-.highlight .cp { color: #9C6500 } /* Comment.Preproc */
-.highlight .cpf { color: #3D7B7B; font-style: italic } /* Comment.PreprocFile */
-.highlight .c1 { color: #3D7B7B; font-style: italic } /* Comment.Single */
-.highlight .cs { color: #3D7B7B; font-style: italic } /* Comment.Special */
-.highlight .gd { color: #A00000 } /* Generic.Deleted */
-.highlight .ge { font-style: italic } /* Generic.Emph */
-.highlight .ges { font-weight: bold; font-style: italic } /* Generic.EmphStrong */
-.highlight .gr { color: #E40000 } /* Generic.Error */
-.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */
-.highlight .gi { color: #008400 } /* Generic.Inserted */
-.highlight .go { color: #717171 } /* Generic.Output */
-.highlight .gp { color: #000080; font-weight: bold } /* Generic.Prompt */
-.highlight .gs { font-weight: bold } /* Generic.Strong */
-.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */
-.highlight .gt { color: #04D } /* Generic.Traceback */
-.highlight .kc { color: #008000; font-weight: bold } /* Keyword.Constant */
-.highlight .kd { color: #008000; font-weight: bold } /* Keyword.Declaration */
-.highlight .kn { color: #008000; font-weight: bold } /* Keyword.Namespace */
-.highlight .kp { color: #008000 } /* Keyword.Pseudo */
-.highlight .kr { color: #008000; font-weight: bold } /* Keyword.Reserved */
-.highlight .kt { color: #B00040 } /* Keyword.Type */
-.highlight .m { color: #666 } /* Literal.Number */
-.highlight .s { color: #BA2121 } /* Literal.String */
-.highlight .na { color: #687822 } /* Name.Attribute */
-.highlight .nb { color: #008000 } /* Name.Builtin */
-.highlight .nc { color: #00F; font-weight: bold } /* Name.Class */
-.highlight .no { color: #800 } /* Name.Constant */
-.highlight .nd { color: #A2F } /* Name.Decorator */
-.highlight .ni { color: #717171; font-weight: bold } /* Name.Entity */
-.highlight .ne { color: #CB3F38; font-weight: bold } /* Name.Exception */
-.highlight .nf { color: #00F } /* Name.Function */
-.highlight .nl { color: #767600 } /* Name.Label */
-.highlight .nn { color: #00F; font-weight: bold } /* Name.Namespace */
-.highlight .nt { color: #008000; font-weight: bold } /* Name.Tag */
-.highlight .nv { color: #19177C } /* Name.Variable */
-.highlight .ow { color: #A2F; font-weight: bold } /* Operator.Word */
-.highlight .w { color: #BBB } /* Text.Whitespace */
-.highlight .mb { color: #666 } /* Literal.Number.Bin */
-.highlight .mf { color: #666 } /* Literal.Number.Float */
-.highlight .mh { color: #666 } /* Literal.Number.Hex */
-.highlight .mi { color: #666 } /* Literal.Number.Integer */
-.highlight .mo { color: #666 } /* Literal.Number.Oct */
-.highlight .sa { color: #BA2121 } /* Literal.String.Affix */
-.highlight .sb { color: #BA2121 } /* Literal.String.Backtick */
-.highlight .sc { color: #BA2121 } /* Literal.String.Char */
-.highlight .dl { color: #BA2121 } /* Literal.String.Delimiter */
-.highlight .sd { color: #BA2121; font-style: italic } /* Literal.String.Doc */
-.highlight .s2 { color: #BA2121 } /* Literal.String.Double */
-.highlight .se { color: #AA5D1F; font-weight: bold } /* Literal.String.Escape */
-.highlight .sh { color: #BA2121 } /* Literal.String.Heredoc */
-.highlight .si { color: #A45A77; font-weight: bold } /* Literal.String.Interpol */
-.highlight .sx { color: #008000 } /* Literal.String.Other */
-.highlight .sr { color: #A45A77 } /* Literal.String.Regex */
-.highlight .s1 { color: #BA2121 } /* Literal.String.Single */
-.highlight .ss { color: #19177C } /* Literal.String.Symbol */
-.highlight .bp { color: #008000 } /* Name.Builtin.Pseudo */
-.highlight .fm { color: #00F } /* Name.Function.Magic */
-.highlight .vc { color: #19177C } /* Name.Variable.Class */
-.highlight .vg { color: #19177C } /* Name.Variable.Global */
-.highlight .vi { color: #19177C } /* Name.Variable.Instance */
-.highlight .vm { color: #19177C } /* Name.Variable.Magic */
-.highlight .il { color: #666 } /* Literal.Number.Integer.Long */
\ No newline at end of file
diff --git a/docs/_build/html/_static/searchtools.js b/docs/_build/html/_static/searchtools.js
deleted file mode 100644
index e29b1c7..0000000
--- a/docs/_build/html/_static/searchtools.js
+++ /dev/null
@@ -1,693 +0,0 @@
-/*
- * Sphinx JavaScript utilities for the full-text search.
- */
-"use strict";
-
-/**
- * Simple result scoring code.
- */
-if (typeof Scorer === "undefined") {
- var Scorer = {
- // Implement the following function to further tweak the score for each result
- // The function takes a result array [docname, title, anchor, descr, score, filename]
- // and returns the new score.
- /*
- score: result => {
- const [docname, title, anchor, descr, score, filename, kind] = result
- return score
- },
- */
-
- // query matches the full name of an object
- objNameMatch: 11,
- // or matches in the last dotted part of the object name
- objPartialMatch: 6,
- // Additive scores depending on the priority of the object
- objPrio: {
- 0: 15, // used to be importantResults
- 1: 5, // used to be objectResults
- 2: -5, // used to be unimportantResults
- },
- // Used when the priority is not in the mapping.
- objPrioDefault: 0,
-
- // query found in title
- title: 15,
- partialTitle: 7,
- // query found in terms
- term: 5,
- partialTerm: 2,
- };
-}
-
-// Global search result kind enum, used by themes to style search results.
-// prettier-ignore
-class SearchResultKind {
- static get index() { return "index"; }
- static get object() { return "object"; }
- static get text() { return "text"; }
- static get title() { return "title"; }
-}
-
-const _removeChildren = (element) => {
- while (element && element.lastChild) element.removeChild(element.lastChild);
-};
-
-/**
- * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#escaping
- */
-const _escapeRegExp = (string) =>
- string.replace(/[.*+\-?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string
-
-const _escapeHTML = (text) => {
- return text
- .replaceAll("&", "&")
- .replaceAll("<", "<")
- .replaceAll(">", ">")
- .replaceAll('"', """)
- .replaceAll("'", "'");
-};
-
-const _displayItem = (item, searchTerms, highlightTerms) => {
- const docBuilder = DOCUMENTATION_OPTIONS.BUILDER;
- const docFileSuffix = DOCUMENTATION_OPTIONS.FILE_SUFFIX;
- const docLinkSuffix = DOCUMENTATION_OPTIONS.LINK_SUFFIX;
- const showSearchSummary = DOCUMENTATION_OPTIONS.SHOW_SEARCH_SUMMARY;
- const contentRoot = document.documentElement.dataset.content_root;
-
- const [docName, title, anchor, descr, score, _filename, kind] = item;
-
- let listItem = document.createElement("li");
- // Add a class representing the item's type:
- // can be used by a theme's CSS selector for styling
- // See SearchResultKind for the class names.
- listItem.classList.add(`kind-${kind}`);
- let requestUrl;
- let linkUrl;
- if (docBuilder === "dirhtml") {
- // dirhtml builder
- let dirname = docName + "/";
- if (dirname.match(/\/index\/$/))
- dirname = dirname.substring(0, dirname.length - 6);
- else if (dirname === "index/") dirname = "";
- requestUrl = contentRoot + dirname;
- linkUrl = requestUrl;
- } else {
- // normal html builders
- requestUrl = contentRoot + docName + docFileSuffix;
- linkUrl = docName + docLinkSuffix;
- }
- let linkEl = listItem.appendChild(document.createElement("a"));
- linkEl.href = linkUrl + anchor;
- linkEl.dataset.score = score;
- linkEl.innerHTML = _escapeHTML(title);
- if (descr) {
- listItem.appendChild(document.createElement("span")).innerHTML =
- ` (${_escapeHTML(descr)})`;
- // highlight search terms in the description
- if (SPHINX_HIGHLIGHT_ENABLED)
- // SPHINX_HIGHLIGHT_ENABLED is set in sphinx_highlight.js
- highlightTerms.forEach((term) =>
- _highlightText(listItem, term, "highlighted"),
- );
- } else if (showSearchSummary)
- fetch(requestUrl)
- .then((responseData) => responseData.text())
- .then((data) => {
- if (data)
- listItem.appendChild(
- Search.makeSearchSummary(data, searchTerms, anchor),
- );
- // highlight search terms in the summary
- if (SPHINX_HIGHLIGHT_ENABLED)
- // SPHINX_HIGHLIGHT_ENABLED is set in sphinx_highlight.js
- highlightTerms.forEach((term) =>
- _highlightText(listItem, term, "highlighted"),
- );
- });
- Search.output.appendChild(listItem);
-};
-const _finishSearch = (resultCount) => {
- Search.stopPulse();
- Search.title.innerText = _("Search Results");
- if (!resultCount)
- Search.status.innerText = Documentation.gettext(
- "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories.",
- );
- else
- Search.status.innerText = Documentation.ngettext(
- "Search finished, found one page matching the search query.",
- "Search finished, found ${resultCount} pages matching the search query.",
- resultCount,
- ).replace("${resultCount}", resultCount);
-};
-const _displayNextItem = (
- results,
- resultCount,
- searchTerms,
- highlightTerms,
-) => {
- // results left, load the summary and display it
- // this is intended to be dynamic (don't sub resultsCount)
- if (results.length) {
- _displayItem(results.pop(), searchTerms, highlightTerms);
- setTimeout(
- () => _displayNextItem(results, resultCount, searchTerms, highlightTerms),
- 5,
- );
- }
- // search finished, update title and status message
- else _finishSearch(resultCount);
-};
-// Helper function used by query() to order search results.
-// Each input is an array of [docname, title, anchor, descr, score, filename, kind].
-// Order the results by score (in opposite order of appearance, since the
-// `_displayNextItem` function uses pop() to retrieve items) and then alphabetically.
-const _orderResultsByScoreThenName = (a, b) => {
- const leftScore = a[4];
- const rightScore = b[4];
- if (leftScore === rightScore) {
- // same score: sort alphabetically
- const leftTitle = a[1].toLowerCase();
- const rightTitle = b[1].toLowerCase();
- if (leftTitle === rightTitle) return 0;
- return leftTitle > rightTitle ? -1 : 1; // inverted is intentional
- }
- return leftScore > rightScore ? 1 : -1;
-};
-
-/**
- * Default splitQuery function. Can be overridden in ``sphinx.search`` with a
- * custom function per language.
- *
- * The regular expression works by splitting the string on consecutive characters
- * that are not Unicode letters, numbers, underscores, or emoji characters.
- * This is the same as ``\W+`` in Python, preserving the surrogate pair area.
- */
-if (typeof splitQuery === "undefined") {
- var splitQuery = (query) =>
- query
- .split(/[^\p{Letter}\p{Number}_\p{Emoji_Presentation}]+/gu)
- .filter((term) => term); // remove remaining empty strings
-}
-
-/**
- * Search Module
- */
-const Search = {
- _index: null,
- _queued_query: null,
- _pulse_status: -1,
-
- htmlToText: (htmlString, anchor) => {
- const htmlElement = new DOMParser().parseFromString(
- htmlString,
- "text/html",
- );
- for (const removalQuery of [".headerlink", "script", "style"]) {
- htmlElement.querySelectorAll(removalQuery).forEach((el) => {
- el.remove();
- });
- }
- if (anchor) {
- const anchorContent = htmlElement.querySelector(
- `[role="main"] ${anchor}`,
- );
- if (anchorContent) return anchorContent.textContent;
-
- console.warn(
- `Anchored content block not found. Sphinx search tries to obtain it via DOM query '[role=main] ${anchor}'. Check your theme or template.`,
- );
- }
-
- // if anchor not specified or not found, fall back to main content
- const docContent = htmlElement.querySelector('[role="main"]');
- if (docContent) return docContent.textContent;
-
- console.warn(
- "Content block not found. Sphinx search tries to obtain it via DOM query '[role=main]'. Check your theme or template.",
- );
- return "";
- },
-
- init: () => {
- const query = new URLSearchParams(window.location.search).get("q");
- document
- .querySelectorAll('input[name="q"]')
- .forEach((el) => (el.value = query));
- if (query) Search.performSearch(query);
- },
-
- loadIndex: (url) =>
- (document.body.appendChild(document.createElement("script")).src = url),
-
- setIndex: (index) => {
- Search._index = index;
- if (Search._queued_query !== null) {
- const query = Search._queued_query;
- Search._queued_query = null;
- Search.query(query);
- }
- },
-
- hasIndex: () => Search._index !== null,
-
- deferQuery: (query) => (Search._queued_query = query),
-
- stopPulse: () => (Search._pulse_status = -1),
-
- startPulse: () => {
- if (Search._pulse_status >= 0) return;
-
- const pulse = () => {
- Search._pulse_status = (Search._pulse_status + 1) % 4;
- Search.dots.innerText = ".".repeat(Search._pulse_status);
- if (Search._pulse_status >= 0) window.setTimeout(pulse, 500);
- };
- pulse();
- },
-
- /**
- * perform a search for something (or wait until index is loaded)
- */
- performSearch: (query) => {
- // create the required interface elements
- const searchText = document.createElement("h2");
- searchText.textContent = _("Searching");
- const searchSummary = document.createElement("p");
- searchSummary.classList.add("search-summary");
- searchSummary.innerText = "";
- const searchList = document.createElement("ul");
- searchList.setAttribute("role", "list");
- searchList.classList.add("search");
-
- const out = document.getElementById("search-results");
- Search.title = out.appendChild(searchText);
- Search.dots = Search.title.appendChild(document.createElement("span"));
- Search.status = out.appendChild(searchSummary);
- Search.output = out.appendChild(searchList);
-
- const searchProgress = document.getElementById("search-progress");
- // Some themes don't use the search progress node
- if (searchProgress) {
- searchProgress.innerText = _("Preparing search...");
- }
- Search.startPulse();
-
- // index already loaded, the browser was quick!
- if (Search.hasIndex()) Search.query(query);
- else Search.deferQuery(query);
- },
-
- _parseQuery: (query) => {
- // stem the search terms and add them to the correct list
- const stemmer = new Stemmer();
- const searchTerms = new Set();
- const excludedTerms = new Set();
- const highlightTerms = new Set();
- const objectTerms = new Set(splitQuery(query.toLowerCase().trim()));
- splitQuery(query.trim()).forEach((queryTerm) => {
- const queryTermLower = queryTerm.toLowerCase();
-
- // maybe skip this "word"
- // stopwords set is from language_data.js
- if (stopwords.has(queryTermLower) || queryTerm.match(/^\d+$/)) return;
-
- // stem the word
- let word = stemmer.stemWord(queryTermLower);
- // select the correct list
- if (word[0] === "-") excludedTerms.add(word.substr(1));
- else {
- searchTerms.add(word);
- highlightTerms.add(queryTermLower);
- }
- });
-
- if (SPHINX_HIGHLIGHT_ENABLED) {
- // SPHINX_HIGHLIGHT_ENABLED is set in sphinx_highlight.js
- localStorage.setItem(
- "sphinx_highlight_terms",
- [...highlightTerms].join(" "),
- );
- }
-
- // console.debug("SEARCH: searching for:");
- // console.info("required: ", [...searchTerms]);
- // console.info("excluded: ", [...excludedTerms]);
-
- return [query, searchTerms, excludedTerms, highlightTerms, objectTerms];
- },
-
- /**
- * execute search (requires search index to be loaded)
- */
- _performSearch: (
- query,
- searchTerms,
- excludedTerms,
- highlightTerms,
- objectTerms,
- ) => {
- const filenames = Search._index.filenames;
- const docNames = Search._index.docnames;
- const titles = Search._index.titles;
- const allTitles = Search._index.alltitles;
- const indexEntries = Search._index.indexentries;
-
- // Collect multiple result groups to be sorted separately and then ordered.
- // Each is an array of [docname, title, anchor, descr, score, filename, kind].
- const normalResults = [];
- const nonMainIndexResults = [];
-
- _removeChildren(document.getElementById("search-progress"));
-
- const queryLower = query.toLowerCase().trim();
- for (const [title, foundTitles] of Object.entries(allTitles)) {
- if (
- title.toLowerCase().trim().includes(queryLower)
- && queryLower.length >= title.length / 2
- ) {
- for (const [file, id] of foundTitles) {
- const score = Math.round(
- (Scorer.title * queryLower.length) / title.length,
- );
- const boost = titles[file] === title ? 1 : 0; // add a boost for document titles
- normalResults.push([
- docNames[file],
- titles[file] !== title ? `${titles[file]} > ${title}` : title,
- id !== null ? "#" + id : "",
- null,
- score + boost,
- filenames[file],
- SearchResultKind.title,
- ]);
- }
- }
- }
-
- // search for explicit entries in index directives
- for (const [entry, foundEntries] of Object.entries(indexEntries)) {
- if (entry.includes(queryLower) && queryLower.length >= entry.length / 2) {
- for (const [file, id, isMain] of foundEntries) {
- const score = Math.round((100 * queryLower.length) / entry.length);
- const result = [
- docNames[file],
- titles[file],
- id ? "#" + id : "",
- null,
- score,
- filenames[file],
- SearchResultKind.index,
- ];
- if (isMain) {
- normalResults.push(result);
- } else {
- nonMainIndexResults.push(result);
- }
- }
- }
- }
-
- // lookup as object
- objectTerms.forEach((term) =>
- normalResults.push(...Search.performObjectSearch(term, objectTerms)),
- );
-
- // lookup as search terms in fulltext
- normalResults.push(
- ...Search.performTermsSearch(searchTerms, excludedTerms),
- );
-
- // let the scorer override scores with a custom scoring function
- if (Scorer.score) {
- normalResults.forEach((item) => (item[4] = Scorer.score(item)));
- nonMainIndexResults.forEach((item) => (item[4] = Scorer.score(item)));
- }
-
- // Sort each group of results by score and then alphabetically by name.
- normalResults.sort(_orderResultsByScoreThenName);
- nonMainIndexResults.sort(_orderResultsByScoreThenName);
-
- // Combine the result groups in (reverse) order.
- // Non-main index entries are typically arbitrary cross-references,
- // so display them after other results.
- let results = [...nonMainIndexResults, ...normalResults];
-
- // remove duplicate search results
- // note the reversing of results, so that in the case of duplicates, the highest-scoring entry is kept
- let seen = new Set();
- results = results.reverse().reduce((acc, result) => {
- let resultStr = result
- .slice(0, 4)
- .concat([result[5]])
- .map((v) => String(v))
- .join(",");
- if (!seen.has(resultStr)) {
- acc.push(result);
- seen.add(resultStr);
- }
- return acc;
- }, []);
-
- return results.reverse();
- },
-
- query: (query) => {
- const [
- searchQuery,
- searchTerms,
- excludedTerms,
- highlightTerms,
- objectTerms,
- ] = Search._parseQuery(query);
- const results = Search._performSearch(
- searchQuery,
- searchTerms,
- excludedTerms,
- highlightTerms,
- objectTerms,
- );
-
- // for debugging
- //Search.lastresults = results.slice(); // a copy
- // console.info("search results:", Search.lastresults);
-
- // print the results
- _displayNextItem(results, results.length, searchTerms, highlightTerms);
- },
-
- /**
- * search for object names
- */
- performObjectSearch: (object, objectTerms) => {
- const filenames = Search._index.filenames;
- const docNames = Search._index.docnames;
- const objects = Search._index.objects;
- const objNames = Search._index.objnames;
- const titles = Search._index.titles;
-
- const results = [];
-
- const objectSearchCallback = (prefix, match) => {
- const name = match[4];
- const fullname = (prefix ? prefix + "." : "") + name;
- const fullnameLower = fullname.toLowerCase();
- if (fullnameLower.indexOf(object) < 0) return;
-
- let score = 0;
- const parts = fullnameLower.split(".");
-
- // check for different match types: exact matches of full name or
- // "last name" (i.e. last dotted part)
- if (fullnameLower === object || parts.slice(-1)[0] === object)
- score += Scorer.objNameMatch;
- else if (parts.slice(-1)[0].indexOf(object) > -1)
- score += Scorer.objPartialMatch; // matches in last name
-
- const objName = objNames[match[1]][2];
- const title = titles[match[0]];
-
- // If more than one term searched for, we require other words to be
- // found in the name/title/description
- const otherTerms = new Set(objectTerms);
- otherTerms.delete(object);
- if (otherTerms.size > 0) {
- const haystack = `${prefix} ${name} ${objName} ${title}`.toLowerCase();
- if (
- [...otherTerms].some((otherTerm) => haystack.indexOf(otherTerm) < 0)
- )
- return;
- }
-
- let anchor = match[3];
- if (anchor === "") anchor = fullname;
- else if (anchor === "-") anchor = objNames[match[1]][1] + "-" + fullname;
-
- const descr = objName + _(", in ") + title;
-
- // add custom score for some objects according to scorer
- if (Scorer.objPrio.hasOwnProperty(match[2]))
- score += Scorer.objPrio[match[2]];
- else score += Scorer.objPrioDefault;
-
- results.push([
- docNames[match[0]],
- fullname,
- "#" + anchor,
- descr,
- score,
- filenames[match[0]],
- SearchResultKind.object,
- ]);
- };
- Object.keys(objects).forEach((prefix) =>
- objects[prefix].forEach((array) => objectSearchCallback(prefix, array)),
- );
- return results;
- },
-
- /**
- * search for full-text terms in the index
- */
- performTermsSearch: (searchTerms, excludedTerms) => {
- // prepare search
- const terms = Search._index.terms;
- const titleTerms = Search._index.titleterms;
- const filenames = Search._index.filenames;
- const docNames = Search._index.docnames;
- const titles = Search._index.titles;
-
- const scoreMap = new Map();
- const fileMap = new Map();
-
- // perform the search on the required terms
- searchTerms.forEach((word) => {
- const files = [];
- // find documents, if any, containing the query word in their text/title term indices
- // use Object.hasOwnProperty to avoid mismatching against prototype properties
- const arr = [
- {
- files: terms.hasOwnProperty(word) ? terms[word] : undefined,
- score: Scorer.term,
- },
- {
- files: titleTerms.hasOwnProperty(word) ? titleTerms[word] : undefined,
- score: Scorer.title,
- },
- ];
- // add support for partial matches
- if (word.length > 2) {
- const escapedWord = _escapeRegExp(word);
- if (!terms.hasOwnProperty(word)) {
- Object.keys(terms).forEach((term) => {
- if (term.match(escapedWord))
- arr.push({ files: terms[term], score: Scorer.partialTerm });
- });
- }
- if (!titleTerms.hasOwnProperty(word)) {
- Object.keys(titleTerms).forEach((term) => {
- if (term.match(escapedWord))
- arr.push({ files: titleTerms[term], score: Scorer.partialTitle });
- });
- }
- }
-
- // no match but word was a required one
- if (arr.every((record) => record.files === undefined)) return;
-
- // found search word in contents
- arr.forEach((record) => {
- if (record.files === undefined) return;
-
- let recordFiles = record.files;
- if (recordFiles.length === undefined) recordFiles = [recordFiles];
- files.push(...recordFiles);
-
- // set score for the word in each file
- recordFiles.forEach((file) => {
- if (!scoreMap.has(file)) scoreMap.set(file, new Map());
- const fileScores = scoreMap.get(file);
- fileScores.set(word, record.score);
- });
- });
-
- // create the mapping
- files.forEach((file) => {
- if (!fileMap.has(file)) fileMap.set(file, [word]);
- else if (fileMap.get(file).indexOf(word) === -1)
- fileMap.get(file).push(word);
- });
- });
-
- // now check if the files don't contain excluded terms
- const results = [];
- for (const [file, wordList] of fileMap) {
- // check if all requirements are matched
-
- // as search terms with length < 3 are discarded
- const filteredTermCount = [...searchTerms].filter(
- (term) => term.length > 2,
- ).length;
- if (
- wordList.length !== searchTerms.size
- && wordList.length !== filteredTermCount
- )
- continue;
-
- // ensure that none of the excluded terms is in the search result
- if (
- [...excludedTerms].some(
- (term) =>
- terms[term] === file
- || titleTerms[term] === file
- || (terms[term] || []).includes(file)
- || (titleTerms[term] || []).includes(file),
- )
- )
- break;
-
- // select one (max) score for the file.
- const score = Math.max(...wordList.map((w) => scoreMap.get(file).get(w)));
- // add result to the result list
- results.push([
- docNames[file],
- titles[file],
- "",
- null,
- score,
- filenames[file],
- SearchResultKind.text,
- ]);
- }
- return results;
- },
-
- /**
- * helper function to return a node containing the
- * search summary for a given text. keywords is a list
- * of stemmed words.
- */
- makeSearchSummary: (htmlText, keywords, anchor) => {
- const text = Search.htmlToText(htmlText, anchor);
- if (text === "") return null;
-
- const textLower = text.toLowerCase();
- const actualStartPosition = [...keywords]
- .map((k) => textLower.indexOf(k.toLowerCase()))
- .filter((i) => i > -1)
- .slice(-1)[0];
- const startWithContext = Math.max(actualStartPosition - 120, 0);
-
- const top = startWithContext === 0 ? "" : "...";
- const tail = startWithContext + 240 < text.length ? "..." : "";
-
- let summary = document.createElement("p");
- summary.classList.add("context");
- summary.textContent =
- top + text.substr(startWithContext, 240).trim() + tail;
-
- return summary;
- },
-};
-
-_ready(Search.init);
diff --git a/docs/_build/html/_static/sphinx_highlight.js b/docs/_build/html/_static/sphinx_highlight.js
deleted file mode 100644
index a74e103..0000000
--- a/docs/_build/html/_static/sphinx_highlight.js
+++ /dev/null
@@ -1,159 +0,0 @@
-/* Highlighting utilities for Sphinx HTML documentation. */
-"use strict";
-
-const SPHINX_HIGHLIGHT_ENABLED = true;
-
-/**
- * highlight a given string on a node by wrapping it in
- * span elements with the given class name.
- */
-const _highlight = (node, addItems, text, className) => {
- if (node.nodeType === Node.TEXT_NODE) {
- const val = node.nodeValue;
- const parent = node.parentNode;
- const pos = val.toLowerCase().indexOf(text);
- if (
- pos >= 0
- && !parent.classList.contains(className)
- && !parent.classList.contains("nohighlight")
- ) {
- let span;
-
- const closestNode = parent.closest("body, svg, foreignObject");
- const isInSVG = closestNode && closestNode.matches("svg");
- if (isInSVG) {
- span = document.createElementNS("http://www.w3.org/2000/svg", "tspan");
- } else {
- span = document.createElement("span");
- span.classList.add(className);
- }
-
- span.appendChild(document.createTextNode(val.substr(pos, text.length)));
- const rest = document.createTextNode(val.substr(pos + text.length));
- parent.insertBefore(span, parent.insertBefore(rest, node.nextSibling));
- node.nodeValue = val.substr(0, pos);
- /* There may be more occurrences of search term in this node. So call this
- * function recursively on the remaining fragment.
- */
- _highlight(rest, addItems, text, className);
-
- if (isInSVG) {
- const rect = document.createElementNS(
- "http://www.w3.org/2000/svg",
- "rect",
- );
- const bbox = parent.getBBox();
- rect.x.baseVal.value = bbox.x;
- rect.y.baseVal.value = bbox.y;
- rect.width.baseVal.value = bbox.width;
- rect.height.baseVal.value = bbox.height;
- rect.setAttribute("class", className);
- addItems.push({ parent: parent, target: rect });
- }
- }
- } else if (node.matches && !node.matches("button, select, textarea")) {
- node.childNodes.forEach((el) => _highlight(el, addItems, text, className));
- }
-};
-const _highlightText = (thisNode, text, className) => {
- let addItems = [];
- _highlight(thisNode, addItems, text, className);
- addItems.forEach((obj) =>
- obj.parent.insertAdjacentElement("beforebegin", obj.target),
- );
-};
-
-/**
- * Small JavaScript module for the documentation.
- */
-const SphinxHighlight = {
- /**
- * highlight the search words provided in localstorage in the text
- */
- highlightSearchWords: () => {
- if (!SPHINX_HIGHLIGHT_ENABLED) return; // bail if no highlight
-
- // get and clear terms from localstorage
- const url = new URL(window.location);
- const highlight =
- localStorage.getItem("sphinx_highlight_terms")
- || url.searchParams.get("highlight")
- || "";
- localStorage.removeItem("sphinx_highlight_terms");
- // Update history only if '?highlight' is present; otherwise it
- // clears text fragments (not set in window.location by the browser)
- if (url.searchParams.has("highlight")) {
- url.searchParams.delete("highlight");
- window.history.replaceState({}, "", url);
- }
-
- // get individual terms from highlight string
- const terms = highlight
- .toLowerCase()
- .split(/\s+/)
- .filter((x) => x);
- if (terms.length === 0) return; // nothing to do
-
- // There should never be more than one element matching "div.body"
- const divBody = document.querySelectorAll("div.body");
- const body = divBody.length ? divBody[0] : document.querySelector("body");
- window.setTimeout(() => {
- terms.forEach((term) => _highlightText(body, term, "highlighted"));
- }, 10);
-
- const searchBox = document.getElementById("searchbox");
- if (searchBox === null) return;
- searchBox.appendChild(
- document
- .createRange()
- .createContextualFragment(
- ''
- + ''
- + _("Hide Search Matches")
- + "
",
- ),
- );
- },
-
- /**
- * helper function to hide the search marks again
- */
- hideSearchWords: () => {
- document
- .querySelectorAll("#searchbox .highlight-link")
- .forEach((el) => el.remove());
- document
- .querySelectorAll("span.highlighted")
- .forEach((el) => el.classList.remove("highlighted"));
- localStorage.removeItem("sphinx_highlight_terms");
- },
-
- initEscapeListener: () => {
- // only install a listener if it is really needed
- if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) return;
-
- document.addEventListener("keydown", (event) => {
- // bail for input elements
- if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName))
- return;
- // bail with special keys
- if (event.shiftKey || event.altKey || event.ctrlKey || event.metaKey)
- return;
- if (
- DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS
- && event.key === "Escape"
- ) {
- SphinxHighlight.hideSearchWords();
- event.preventDefault();
- }
- });
- },
-};
-
-_ready(() => {
- /* Do not call highlightSearchWords() when we are on the search page.
- * It will highlight words from the *previous* search query.
- */
- if (typeof Search === "undefined") SphinxHighlight.highlightSearchWords();
- SphinxHighlight.initEscapeListener();
-});
diff --git a/docs/_build/html/genindex.html b/docs/_build/html/genindex.html
deleted file mode 100644
index 11afc13..0000000
--- a/docs/_build/html/genindex.html
+++ /dev/null
@@ -1,2334 +0,0 @@
-
-
-
-
-
- Index — PowerGridSynth 0.1.1 documentation
-
-
-
-
-
-
- PowerGridSynth
-
-
-
-
-
-
-
-
-
-
Index
-
-
-
_
- |
A
- |
B
- |
C
- |
D
- |
E
- |
F
- |
G
- |
H
- |
I
- |
K
- |
L
- |
M
- |
N
- |
O
- |
P
- |
R
- |
S
- |
T
- |
V
-
-
-
_
-
-
-
A
-
-
-
B
-
-
-
C
-
-
-
D
-
-
-
E
-
-
-
F
-
-
-
G
-
-
-
H
-
-
-
I
-
-
-
K
-
-
-
L
-
-
-
M
-
-
-
N
-
-
-
O
-
-
-
P
-
-
-
R
-
-
-
S
-
-
-
T
-
-
-
V
-
-
-
-
-
-
-
-
-
-
PowerGridSynth — PowerGridSynth 0.1.1 documentation
-
-
-
-
-
-
- PowerGridSynth
-
-
-
-
-
-
-
-
-
-PowerGridSynth
-PowerGridSynth is an open-source Python package for generating realistic synthetic power grids at both the transmission and distribution level.
-
-Transmission grids are synthesized using a Chung-Lu-Chain (CLC) graph model that reproduces prescribed degree distributions and diameters across multiple voltage levels, then layers on bus-type assignment, generation/load capacity allocation (active and reactive power), generation dispatch, and transmission-line impedance/capacity assignment drawn from empirical statistics of real grids (NYISO, WECC).
Distribution feeders are synthesized using the algorithm of Schweitzer et al. (2017) , producing radial MV/LV tree graphs with realistic cable types, lengths, and load/generation profiles.
-Synthesised grids can be exported to 12+ industry-standard formats via pandapower and pypowsybl and validated with DC and AC power-flow solvers from both libraries.
-The goal of the project is to provide synthetic yet realistic power grids for grid modeling, simulation and analysis, with the ultimate goal of building Foundation Models for power grids. It is part of LF Energy , a Linux Foundation focused on the energy sector. This project is supported by AI-EFFECT (Artificial Intelligence Experimentation Facility For the Energy Sector).
-
-Transmission Grid Synthesis
-
-Synthesis Pipeline
-
-
-
-
-Step
Module
Method
-
-1
Topology generation
CLC graph model with prescribed degree distribution and diameter per voltage level; k-stars inter-level transformer model
2
Bus-type assignment
Entropy-based Artificial Immune System (AIS) optimisation reproducing empirical 2-D joint distribution of bus types and node degrees
3
Generation capacity
Exponential/extreme-value sampling with capacity–degree correlation via 2-D PMF table
4
Load allocation
Empirical 2-D probability table matching load–degree joint distribution; reactive loads via power-factor model
5
Generation dispatch
Three-category partitioning (uncommitted / partially committed / fully committed) with 2-D bin matching and iterative balancing
6
Transmission lines
LogNormal impedance magnitudes, Lévy-stable line angles, DCPF-based swapping, exponential gauge-ratio assignment via 2-D table
-
-
-
-Quick Start
-The high-level synthesize()
-from powergrid_synth import synthesize
-
-# Mode I — clone an existing grid's statistical profile
-grid = synthesize (
- mode = "reference" ,
- reference_case = "case118" ,
- seed = 42 ,
- export_formats = [ "json" , "cgmes" , "matpower" ],
-)
-
-# Mode II — fully synthetic from user-specified parameters
-grid = synthesize (
- mode = "synthetic" ,
- level_specs = [
- { "n" : 50 , "avg_k" : 3.5 , "diam" : 10 , "dist_type" : "dgln" },
- { "n" : 150 , "avg_k" : 2.5 , "diam" : 15 , "dist_type" : "dpl" },
- { "n" : 300 , "avg_k" : 2.0 , "diam" : 20 , "dist_type" : "poisson" },
- ],
- connection_specs = {
- ( 0 , 1 ): { "type" : "k-stars" , "c" : 0.174 , "gamma" : 4.15 },
- ( 1 , 2 ): { "type" : "k-stars" , "c" : 0.15 , "gamma" : 4.15 },
- },
- seed = 42 ,
- export_formats = [ "json" , "matpower" ],
-)
-
-
See examples/Synthesize.nblink for a full walkthrough.
-
-
-Step-by-Step Usage
-For fine-grained control over individual pipeline stages:
-from powergrid_synth import (
- InputConfigurator , PowerGridGenerator , BusTypeAllocator ,
- CapacityAllocator , LoadAllocator , GenerationDispatcher ,
- TransmissionLineAllocator , GridVisualizer ,
-)
-
-# 1. Configure voltage levels and inter-level connections
-level_specs = [
- { 'n' : 50 , 'avg_k' : 3.5 , 'diam' : 10 , 'dist_type' : 'dgln' },
- { 'n' : 150 , 'avg_k' : 2.5 , 'diam' : 15 , 'dist_type' : 'dpl' },
- { 'n' : 300 , 'avg_k' : 2.0 , 'diam' : 20 , 'dist_type' : 'poisson' },
-]
-connection_specs = {
- ( 0 , 1 ): { 'type' : 'k-stars' , 'c' : 0.174 , 'gamma' : 4.15 },
- ( 1 , 2 ): { 'type' : 'k-stars' , 'c' : 0.15 , 'gamma' : 4.15 },
-}
-
-config = InputConfigurator ( seed = 42 )
-params = config . create_params ( level_specs , connection_specs )
-
-# 2. Generate topology (CLC model)
-gen = PowerGridGenerator ( seed = 42 )
-grid = gen . generate_grid (
- degrees_by_level = params [ 'degrees_by_level' ],
- diameters_by_level = params [ 'diameters_by_level' ],
- transformer_degrees = params [ 'transformer_degrees' ],
-)
-
-# 3. Assign bus types, generation/load, dispatch, and line parameters
-BusTypeAllocator ( grid ) . allocate ()
-CapacityAllocator ( grid ) . allocate ()
-LoadAllocator ( grid ) . allocate ()
-GenerationDispatcher ( grid ) . dispatch ()
-TransmissionLineAllocator ( grid ) . allocate ()
-
-# 4. Visualize
-GridVisualizer () . plot_grid ( grid , layout = 'yifan_hu' , title = "Synthetic Grid" )
-
-
See the Examples
-
-
-
-Distribution Grid Synthesis
-
-Quick Start
-The high-level synthesize_distribution()
-from powergrid_synth import synthesize_distribution
-
-# Mode I — fit parameters from a reference distribution network
-feeders = synthesize_distribution (
- mode = "reference" ,
- reference_case = "cigre_lv" ,
- n_feeders = 5 ,
- n_nodes = 20 ,
- total_load_mw = 0.5 ,
- seed = 42 ,
- output_dir = "output" ,
- export_formats = [ "json" ],
-)
-
-# Mode II — use default Table III parameters (no reference needed)
-feeders = synthesize_distribution (
- mode = "default" ,
- n_feeders = 10 ,
- n_nodes = 30 ,
- total_load_mw = 0.8 ,
- seed = 7 ,
-)
-
-
See examples/DistributionSynth.nblink and examples/DistributionSynthFromRef.nblink for detailed walkthroughs.
-
-
-
-
-
-
-
-
-
-
-
-
API Reference — PowerGridSynth 0.1.1 documentation
-
-
-
-
-
-
- PowerGridSynth
-
-
-
-
-
-
-
-
-
-API Reference
-
-Transmission Grid Synthesis
-
-High-Level Function
-
-
-powergrid_synth. synthesize ( * mode reference_case = None reference_net = None reference_file = None level_specs = None connection_specs = None seed = None keep_lcc = True entropy_model = 0 bus_type_ratio = None ref_sys_id = 1 loading_level = 'H' refine_topology = False base_kv_map = None output_dir = 'output' output_name = 'synthetic_grid' export_formats = ('json',) ) [source]
-Run the full CLC synthesis pipeline and export the result.
-
-Parameters:
-
-mode ("reference" "synthetic"
Selects the operation mode.
-
-reference_case (str , optional ) – Name of a built-in network. Supports both pandapower case names
-(e.g. "case118" "ieee14" "ieee118" reference_net or
-reference_file is given.
reference_net (pandapowerNet or pypowsybl.network.Network , optional ) – A pre-loaded network object (pandapower or pypowsybl). Takes
-precedence over reference_case and reference_file .
reference_file (str , optional ) – Path to a grid file in any pypowsybl-supported format (CGMES,
-XIIDM, MATPOWER, IEEE-CDF, PSS/E, UCTE, etc.). Takes
-precedence over reference_case .
level_specs (list of dict , optional ) – Voltage-level specifications for Mode II. Each dict must have
-keys "n" "avg_k" "diam" "dist_type" "dgln" "dpl" "poisson" "max_k"
connection_specs (dict , optional ) – Transformer connection specs for Mode II. Maps
-(level_i, level_j) "type" "k-stars" "simple" "c" "gamma"
seed (int , optional ) – Random seed for reproducibility.
keep_lcc (bool ) – If True
entropy_model (int ) – Bus-type entropy model — 0 (standard) or 1 (weighted).
bus_type_ratio (list of float , optional ) – Target [Gen%, Load%, Conn%] None
ref_sys_id (int ) – Reference system for statistical tables (0–3).
loading_level (str ) – Load level — "D" "L" "M" "H"
refine_topology (bool ) – If True
base_kv_map (dict , optional ) – Custom {level_index: kV} None mode="reference"
output_dir (str ) – Directory for exported files (created if needed).
output_name (str ) – Base filename (without extension) for exported files.
export_formats (sequence of str ) – One or more format names to export. Supported:
-"json" "excel" "sqlite" "pickle" "xiidm" "cgmes" "matpower" "psse"
-Returns:
-The fully parameterised synthetic grid (a
-PowerGridGraph
-Return type:
-nx.Graph
-Raises:
-ValueError – If mode is not "reference" "synthetic"
-
-
-
-
-
-Topology Generation
-
-
-class powergrid_synth. InputConfigurator ( seed = None ) [source]
-Bases: object
-Generate detailed input sequences for PowerGridGenerator
-This is “operation mode II”, where the user specifies only the number of
-nodes, average degree, diameter, and distribution type for each voltage
-level, rather than providing explicit degree sequences. The configurator
-uses DegreeDistributionOptimizer
-See Section 6 of Aksoy et al. (2018) for the synthetic input
-generation guidelines.
-
-Parameters:
-seed (int or None , optional ) – Random seed for reproducibility. Default is None.
-
-
-
-create_params ( levels inter_connections ) [source]
-Generate the full parameter set for PowerGridGenerator.generate_grid()
-
-Parameters:
-
-levels (list of dict ) –
One dict per voltage level with keys:
-
-'n'
'avg_k'
'diam'
'dist_type' 'dgln' 'dpl' 'poisson'
'max_k' min(n - 1, 50) 'dpl' \(d_{\max} \approx 1.517\,n^{1/4}\) ; for 'dgln' \(\bar{d} \approx 2.425 \pm 0.185\) is consistent across
-subgraphs (Section 6.1 of Aksoy et al., 2018).
-inter_connections (dict ) –
Mapping (i, j) -> config
-
-{'type': 'k-stars', 'c': 0.174, 'gamma': 4.15}
{'type': 'simple', 'p_i_j': float, 'p_j_i': float}
-
-Returns:
-Keys 'degrees_by_level' 'diameters_by_level' 'transformer_degrees' PowerGridGenerator.generate_grid()
-Return type:
-dict
-
-
-
-
-
-
-
-class powergrid_synth. PowerGridGenerator ( seed = None ) [source]
-Bases: object
-Generative model for an entire power grid graph on k voltage levels.
-Implements Algorithm 4 (CLCStars) from Aksoy et al. (2018) .
-Phase 1 generates each same-voltage subgraph via the CLC model,
-and Phase 2 inserts transformer edges via the random-star model.
-
-Parameters:
-seed (int or None , optional ) – Random seed for reproducibility. Default is None.
-
-
-
-generate_grid ( degrees_by_level diameters_by_level transformer_degrees keep_lcc = False ) [source]
-Generate a multi-level power grid graph (CLCStars, Algorithm 4).
-Runs Phase 1 (CLC for each voltage level) and Phase 2 (random-star
-transformer edges for each pair of levels), then combines results.
-
-Parameters:
-
-degrees_by_level (list of list of int ) – Desired degree sequences \(\mathbf{d}^{X_1},\dots,\mathbf{d}^{X_k}\) ,
-one per voltage level.
diameters_by_level (list of int ) – Desired diameters \(\delta^{X_1},\dots,\delta^{X_k}\) ,
-one per voltage level.
transformer_degrees (dict ) – Mapping (i, j) -> (t_i_j, t_j_i) t_i_j i nodes toward level j ,
-and t_j_i
keep_lcc (bool , optional ) – If True, return only the largest connected component with
-contiguous node IDs. Default is False.
-Returns:
-The generated grid graph with voltage_level type 'line' 'transformer'
-Return type:
-PowerGridGraph
-
-
-
-
-
-
-
-Electrical Assignment
-
-
-class powergrid_synth. BusTypeAllocator ( graph entropy_model = 0 bus_type_ratio = None ) [source]
-Bases: object
-Assigns bus types (Generator, Load, Connection) to a raw power grid
-topology using an Artificial Immune System (AIS) optimization algorithm.
-The method, from Elyas and Wang (2016), exploits the observed non-trivial
-correlations between bus types and topology metrics (node degree, clustering
-coefficient) in realistic grids. A bus type entropy measure quantifies
-these correlations, and a target entropy \(W^*\) is derived from a
-scaling property fitted to real-world systems. The AIS then searches for
-an assignment whose entropy matches \(W^*\) .
-The pipeline is:
-
-Determine target bus type ratios \((r_G, r_L, r_C)\) from network
-size.
Estimate \(W^*\) via Monte Carlo sampling of random assignments
-and the scaling relation \(W^* = \mu + \sigma \cdot d(N)\) .
Run AIS optimization (clonal selection, hypermutation, receptor editing)
-to find an assignment \(\mathbb{T}\) such that
-\(|W(\mathbb{T}) - W^*| < \epsilon\) .
-Two entropy definitions are supported:
-
-Model 0 (\(W_0\) ): standard entropy of bus/link type ratios.
-\(\mu\) is stable across network sizes.
Model 1 (\(W_1\) ): generalized entropy weighted by \(N\)
-and \(M\) . \(\mu\) grows with network size, giving better
-discrimination in large grids.
-
-Parameters:
-
-graph (nx.Graph ) – NetworkX graph representing the grid topology (nodes and edges only;
-no bus type attributes required yet).
entropy_model (int ) – Selects the entropy definition: 0 for \(W_0\) , 1 for \(W_1\) .
bus_type_ratio (list of float or None ) – Optional target ratios [Gen, Load, Conn] None , default ratios are chosen based on N .
-
-References
-
-
-
-TYPE_CONN = 3
-
-
-
-
-TYPE_GEN = 1
-
-
-
-
-TYPE_LOAD = 2
-
-
-
-
-allocate ( max_iter = 100 population_size = 20 ) [source]
-Run the AIS optimization to find a bus type assignment.
-Implements the Clonal Selection Principle:
-
-Monte Carlo estimation of \(W^*\) and convergence
-threshold \(\epsilon\) (see _estimate_w_star()
Initialize a population of K random assignments.
Iterate until max_iter best_error < epsilon
-
-Evaluate fitness \(|W^* - W(\mathbb{T})|\) for each
-individual.
Clonal selection — top-ranked individuals produce more
-clones: \(N_c = \text{round}(\beta \cdot s / r)\) where
-r is the rank.
Hypermutation — clones are mutated with intensity
-proportional to their parent’s rank (worse → more mutations).
Receptor editing — inject 10% fresh random solutions to
-maintain diversity and avoid local optima.
Selection — combine elite, mutated clones, and fresh
-solutions; keep the top K .
-Return the best assignment found.
-
-Parameters:
-
-max_iter (int , optional ) – Maximum number of AIS iterations (default 100).
population_size (int , optional ) – Number of individuals surviving each generation (default 20).
-Returns:
-Mapping from node ID to bus type label
-('Gen' 'Load' 'Conn'
-Return type:
-dict[int, str]
-
-
-
-
-
-plot_entropy_pdf ( figsize = (10, 6) ) [source]
-Plot the empirical PDF of entropy samples from the Monte Carlo
-estimation, with a fitted normal distribution overlay.
-Must be called after allocate() _estimate_w_star() self.w_samples
-
-Parameters:
-figsize (tuple of int , optional ) – Figure size (width, height)
-
-
-
-
-
-
-
-class powergrid_synth. CapacityAllocator ( graph ref_sys_id = 1 ) [source]
-Bases: object
-Assigns generation capacities (PgMax) to generator buses in the grid.
-Implements the three-stage methodology from Elyas et al. (2017):
-
-Total generation: Compute the aggregate generation capacity from a
-scaling law fitted to realistic grids:
-log Pg_tot(N) = -0.21 * log^2(N) + 2.06 * log(N) + 0.66
Individual capacities: Sample N_g individual capacities from an
-exponential distribution (with ~1% super-large outliers to capture the
-observed heavy tail).
Correlated assignment: Assign capacities to generator buses using a
-14x14 empirical 2D probability table (Tab_2D_Pgmax
-Reference systems with pre-computed Tab_2D_Pgmax
-
-Parameters:
-
-graph (nx.Graph ) – NetworkX graph with 'bus_type' BusTypeAllocator
ref_sys_id (int ) – Reference system for statistical tables (0=heuristic, 1=NYISO-2935,
-2=WECC-16944, 3=additional reference).
-
-References
-
-
-
-allocate ( tab_2d = None ) [source]
-Run the full generation-capacity allocation pipeline.
-Executes the three-stage methodology from Elyas et al. (2017):
-
-Compute total generation capacity from the scaling law:
-Pg_tot = 10^(-0.21 * log10(N)^2 + 2.06 * log10(N) + 0.66)
Sample individual capacities, normalize them and the generator
-nodal degrees by their respective maxima so that both lie in
-[0, 1]: P_bar = P / max(P) k_bar = k / max(k)
Assign normalized capacities to generator buses via 2D binning
-using Tab_2D_Pgmax
Denormalize: Pg_max = P_bar * max(P)
-
-Parameters:
-tab_2d (np.ndarray or None , optional ) – Custom 14x14 probability matrix. If None , the default table
-for the selected ref_sys_id
-Returns:
-Mapping from generator node ID to its assigned capacity
-Pg_max
-Return type:
-dict[int, float]
-
-
-
-
-
-
-
-class powergrid_synth. LoadAllocator ( graph ref_sys_id = 1 ) [source]
-Bases: object
-Assigns active power loads (PL) to load buses in the grid.
-Implements the load-setting methodology from Elyas et al. (2017), which
-mirrors the generation-capacity approach in CapacityAllocator
-
-Total load: Compute an aggregate load target, either from a
-deterministic scaling formula or as a fraction (light / medium / heavy)
-of the total installed generation capacity.
Individual loads: Sample N_l individual loads from an exponential
-distribution (with ~1% super-large outliers).
Correlated assignment: Assign loads to load buses using a 14x14
-empirical 2D probability table (Tab_2D_load
-Reference systems with pre-computed Tab_2D_load
-
-Parameters:
-
-graph (nx.Graph ) – NetworkX graph with 'bus_type' 'pg_max'
ref_sys_id (int ) – Reference system for statistical tables (0=heuristic, 1=NYISO-2935,
-2=WECC-16944, 3=additional reference).
-
-References
-
-
-
-allocate ( loading_level = 'H' ) [source]
-Run the full load-allocation pipeline.
-Executes the three-stage methodology (analogous to
-CapacityAllocator.allocate()
-
-Compute total system load from loading_level
Sample individual loads, normalize them and the load-bus nodal
-degrees by their respective maxima:
-P_bar = P / max(P) k_bar = k / max(k)
Assign normalized loads to load buses via 2D binning using
-Tab_2D_load
Denormalize: PL = P_bar * max(P)
-
-Parameters:
-loading_level (str , optional ) –
Loading strategy (default 'H'
-
-'D'
'L'
'M'
'H'
-
-Returns:
-Mapping from load node ID to its assigned active power load (MW).
-Return type:
-dict[int, float]
-
-
-
-
-
-allocate_reactive ( active_loads pf_min = 0.85 pf_max = 0.97 ) [source]
-Derive reactive power loads from active loads using power factors.
-For each load bus, a power factor is sampled uniformly from
-[pf_min, pf_max] ql = pl * tan(arccos(pf))
-Theory reference:
-https://www.phasetophase.nl/book/book_2_9.html#_9.5.2
-
-Parameters:
-
-active_loads (dict [ int , float ] ) – Mapping from load node ID to active power load (MW), as returned
-by allocate()
pf_min (float , optional ) – Minimum power factor (default 0.85).
pf_max (float , optional ) – Maximum power factor (default 0.97).
-Returns:
-Mapping from load node ID to reactive power load (Mvar).
-Return type:
-dict[int, float]
-
-
-
-
-
-
-
-class powergrid_synth. GenerationDispatcher ( graph ref_sys_id = 1 ) [source]
-Bases: object
-Assign active-power dispatch to each generator bus.
-The algorithm follows Sadeghian et al. (2018) (Section III):
-
-Uncommitted units (10–20 %): \(\alpha = 0\) , selected via
-targets drawn from Uniform[0, 0.6].
Partially committed units (40–50 %): selected via exponential
-distribution on capacity; dispatch factors assigned through a
-2-D bin-matching table Tab_2D_Pg \(14 \times 10\) ).
Fully committed units (remainder): \(\alpha = 1\) .
Balancing loop : iteratively adjusts dispatch to match total
-load within 1 % tolerance.
-
-Parameters:
-
-graph (networkx.Graph ) – Power grid graph. Generator nodes must have 'bus_type' == 'Gen' 'pg_max' 'pl'
ref_sys_id (int , optional ) – Reference system for statistical tables (1 = NYISO-2935,
-2 = WECC-16994, 3 = additional reference). Default is 1.
-
-
-
-alpha_mod
-Loading-level flag from the reference system. When 0 all alphas
-are Uniform[0, 1]; otherwise 0.5 % receive negative dispatch
-(e.g., pumped-storage hydro).
-
-Type:
-int
-
-
-
-
-
-mu_committed
-Exponential-distribution parameter for committed-unit capacities.
-
-Type:
-float
-
-
-
-
-
-tab_2d_pg
-2-D empirical PMF table (14 capacity bins × 10 alpha bins).
-
-Type:
-numpy.ndarray
-
-
-
-
-
-dispatch ( ) [source]
-Run the full generation dispatch pipeline.
-Implements the algorithm of Sadeghian et al. (2018):
-
-Collect generator buses and normalise capacities by
-\(P^{\max}_{g_{\max}}\) .
Partition generators into uncommitted
-(\(\alpha = 0\) ), partially committed
-(\(0 < \alpha < 1\) ), and fully committed
-(\(\alpha = 1\) ).
Assign dispatch factors to partially committed units via
-the 2-D bin-matching table Tab_2D_Pg
Iteratively balance total generation against total load
-(1 % tolerance, up to 50 iterations) by scaling committed
-\(\alpha\) values and toggling uncommitted / full-load
-units on or off.
Convert normalised dispatch back to MW:
-\(P_{g_i} = \alpha_i \cdot \bar{P}_{g_i}^{\max} \cdot P^{\max}_{g_{\max}}\) .
-
-Returns:
-Mapping of generator bus ID to dispatched active power (MW).
-Return type:
-dict
-
-
-
-
-
-
-
-class powergrid_synth. TransmissionLineAllocator ( graph ref_sys_id = 1 ) [source]
-Bases: object
-Allocate impedance and capacity limits to transmission lines.
-The algorithm follows Sadeghian et al. (2018) and the SynGrid
-MATLAB toolbox (sg_line.m sg_flow_lim.m
-
-Impedance generation — magnitudes \(Z\) from
-LogNormal(\(\mu\) , \(\sigma\) ), angles \(\varphi\)
-from a Lévy stable distribution
-\(S(\alpha_s, \beta_s, \gamma_s, \delta_s)\) . Then
-\(X = Z \sin\varphi\) , \(R = Z \cos\varphi\) .
DCPF-based swapping — sort impedances ascending and flows
-descending, then randomly swap ~20–30 % of assignments to
-introduce variance while preserving the negative correlation
-between impedance and flow.
(Optional) Topology refinement — iteratively add
-low-impedance lines between max angle-difference bus pairs
-and remove weak high-\(X\) lines until the angle spread
-is below a size-dependent threshold.
Capacity assignment — gauge ratios
-\(\beta_l = F_l / F_l^{\max}\) from
-Exponential(\(\mu_\beta\) ) with overload injection;
-assigned via 2-D table Tab_2D_FlBeta \(F_l^{\max} = F_l / \beta_l\) .
-
-Parameters:
-
-graph (networkx.Graph ) – Power grid graph with nodal generation/load attributes.
ref_sys_id (int , optional ) – Reference system (1 = NYISO-2935, 2 = WECC-16994). Default 1.
-
-
-
-stab_params
-Lévy stable parameters \([\alpha_s, \beta_s, \gamma_s, \delta_s]\) .
-
-Type:
-list of float
-
-
-
-
-
-tab_fl_beta
-2-D empirical PMF table for flow–beta assignment.
-
-Type:
-numpy.ndarray
-
-
-
-
-
-mu_beta
-Mean of the exponential distribution for \(\beta\) .
-
-Type:
-float
-
-
-
-
-
-overload_b
-Fraction of lines assigned overload (\(\beta > 1\) ).
-
-Type:
-float
-
-
-
-
-
-allocate ( refine_topology = False ) [source]
-Run the full transmission-line allocation pipeline.
-Executes the seven-step procedure:
-
-Draw impedance magnitudes
-\(Z \sim \text{LogNormal}(\mu, \sigma)\) , clipped to
-[0.001, 0.5] p.u.
Generate angles \(\varphi\) (Lévy stable), compute
-\(X = Z\sin\varphi\) , \(R = Z\cos\varphi\) .
Iterative DCPF swapping: sort \(Z\) ascending / flows
-descending, randomly swap ~20–30 % of assignments.
(Optional) Topology refinement via _refine_topology()
Final DCPF to obtain converged flows.
Generate and assign gauge ratios (\(\beta\) ) via
-_generate_beta() _assign_betas()
Set capacity limits:
-\(F_l^{\max} = F_l / \beta_l\) with a minimum-capacity
-fallback (5 + 100 · rand MW when \(\le 2\) ).
-
-Parameters:
-refine_topology (bool , optional ) – If True False
-Returns:
-Mapping (u, v)
-Return type:
-dict
-
-
-
-
-
-
-
-
-Distribution Grid Synthesis
-
-High-Level Function
-
-
-powergrid_synth. synthesize_distribution ( * mode reference_case = None reference_net = None reference_file = None params = None n_feeders = 1 n_nodes = 20 total_load_mw = 0.5 total_gen_mw = 0.0 v_nom_kv = 10.0 assign_cable_types = True assign_cable_lengths = True seed = None output_dir = None output_name = 'synthetic_feeder' export_formats = ('json',) ) [source]
-Run the full Schweitzer distribution synthesis pipeline.
-
-Parameters:
-
-mode ("reference" "default"
Selects the operation mode.
-
-"reference"
"default" DistributionSynthParams
-reference_case (str , optional ) – Short name of a built-in distribution network. Currently
-supported: "cigre_lv" "cigre_mv" reference_net or
-reference_file is given.
reference_net (pandapowerNet or pypowsybl.network.Network , optional ) – A pre-loaded network object. Takes precedence over
-reference_case and reference_file .
reference_file (str , optional ) – Path to a grid file in any pypowsybl-supported format.
params (DistributionSynthParams , optional ) – Custom parameters for mode="default" None
n_feeders (int ) – Number of synthetic feeders to generate (default 1).
n_nodes (int ) – Number of nodes per feeder (default 20).
total_load_mw (float ) – Total load in MW per feeder (default 0.5).
total_gen_mw (float ) – Total generation in MW per feeder (default 0.0).
v_nom_kv (float ) – Nominal voltage in kV (default 10.0).
assign_cable_types (bool ) – Run Step 4 — cable type assignment (default True).
assign_cable_lengths (bool ) – Run Step 5 — cable length / impedance assignment (default True).
seed (int , optional ) – Random seed for reproducibility.
output_dir (str , optional ) – If given, export feeders to this directory.
output_name (str ) – Base filename (without extension) for exported files.
export_formats (sequence of str ) – Export formats when output_dir is set. Supported:
-"json" "excel" "sqlite" "pickle"
-Returns:
-Generated synthetic feeders as annotated NetworkX graphs.
-Return type:
-list[nx.Graph]
-Raises:
-ValueError – If mode is invalid or required arguments are missing.
-
-
-
-
-
-Core Classes
-
-
-class powergrid_synth.distribution. SchweetzerFeederGenerator ( params = None seed = None ) [source]
-Bases: object
-Generate a single MV radial distribution feeder.
-
-Parameters:
-
-params (DistributionSynthParams , optional ) – All distribution parameters. Defaults to Table III values.
seed (int or None , optional ) – Random seed for reproducibility.
-
-
-
-generate_feeder ( n_nodes total_load_mw total_gen_mw = 0.0 v_nom_kv = 10.0 assign_cable_types = True assign_cable_lengths = True ) [source]
-Generate a complete MV distribution feeder.
-
-Parameters:
-
-n_nodes (int ) – Total number of nodes in the feeder (including source and root).
total_load_mw (float ) – Total real-power load (MW) to be distributed across load buses.
total_gen_mw (float , optional ) – Total real-power generation/injection (MW). Default 0.
v_nom_kv (float , optional ) – Nominal MV voltage in kV. Default 10.
assign_cable_types (bool , optional ) – Whether to run Step 4 (cable type assignment). Default True.
assign_cable_lengths (bool , optional ) – Whether to run Step 5 (cable length and impedance assignment).
-Default True.
-Returns:
-Annotated graph with node attributes (h P_mw Q_mvar pf node_type cable_type length_km r_ohm x_ohm max_i_ka I_est_ka
-Return type:
-nx.Graph
-
-
-
-
-
-
-
-class powergrid_synth.distribution. DistributionSynthParams ( hop_dist = <factory> pf_cdf = <factory> degree_dist = <factory> degree_clip = <factory> intermediate_frac = <factory> intermediate_hop = <factory> injection_frac = <factory> injection_hop = <factory> injection_deviation = <factory> load_deviation = <factory> cable_library = <factory> current_ratio = <factory> current_threshold = <factory> cable_length = <factory> length_clip = <factory> ) [source]
-Bases: object
-All parameters for the Schweitzer distribution feeder generator.
-Default values are taken from Table III and the text of
-Schweitzer et al. (2017).
-
-Parameters:
-
-
-
-
-
-cable_length : ModifiedCauchyParams
-
-
-
-
-cable_library : List [ CableLibraryEntry ]
-
-
-
-
-current_ratio : ExponentialParams
-
-
-
-
-current_threshold : CurrentThreshold
-
-
-
-
-degree_clip : PowerLawClip
-
-
-
-
-degree_dist : MixtureGammaParams
-
-
-
-
-hop_dist : NegBinomParams
-
-
-
-
-injection_deviation : NormalParams
-
-
-
-
-injection_frac : BetaParams
-
-
-
-
-injection_hop : MixtureNormalParams
-
-
-
-
-intermediate_frac : BetaParams
-
-
-
-
-intermediate_hop : MixturePoissonParams
-
-
-
-
-length_clip : ExponentialClip
-
-
-
-
-load_deviation : TLocationScaleParams
-
-
-
-
-pf_cdf : List [ tuple ]
-
-
-
-
-
-
-class powergrid_synth.distribution. DistributionInputModel ( bw_method = None seed = None ) [source]
-Bases: object
-3-D KDE input model for feeder size and loading.
-The model is fitted on reference feeders and then sampled to produce
-realistic (n_nodes, total_load, total_gen)
-
-Parameters:
-
-bw_method (str or float , optional ) – Bandwidth method passed to scipy.stats.gaussian_kde
seed (int or None , optional ) – Random seed for reproducibility.
-
-
-
-fit ( feeders ) [source]
-Fit the KDE from a collection of reference feeder graphs.
-Each graph must have node attributes P_mw
-
-Parameters:
-feeders (sequence of nx.Graph ) – Reference feeder graphs.
-Return type:
-self
-
-
-
-
-
-fit_from_arrays ( n_nodes total_load total_gen ) [source]
-Fit directly from arrays (no graph objects needed).
-
-Parameters:
-
-n_nodes (array-like of int )
total_load (array-like of float )
total_gen (array-like of float )
-Return type:
-self
-
-
-
-
-
-pdf ( n_nodes total_load total_gen ) [source]
-Evaluate the KDE density at a given point.
-
-Parameters:
-
-n_nodes (float ) – Coordinates in the 3-D input space.
total_load (float ) – Coordinates in the 3-D input space.
total_gen (float ) – Coordinates in the 3-D input space.
-Returns:
-Estimated probability density.
-Return type:
-float
-
-
-
-
-
-sample ( n_samples = 1 ) [source]
-Draw samples from the fitted input model.
-
-Parameters:
-n_samples (int ) – Number of samples to draw.
-Return type:
-list of FeederInputSample
-
-
-
-
-
-
-
-Analysis & Conversion
-
-
-powergrid_synth.distribution. fit_params_from_feeders ( feeders ) [source]
-Fit all Schweitzer parameters from a collection of reference feeders.
-
-Parameters:
-feeders (sequence of nx.Graph ) – Reference distribution feeder graphs, each annotated with
-h P_mw node_type length_km
-Returns:
-Fitted parameter set ready for SchweetzerFeederGenerator
-Return type:
-DistributionSynthParams
-
-
-
-Conversion utilities for building Schweitzer-format feeder graphs
-from pandapower and pypowsybl reference networks.
-
-
-powergrid_synth.distribution.distribution_converter. feeder_summary ( feeders ) [source]
-Return a summary dict for each feeder graph.
-
-Parameters:
-feeders (sequence of nx.Graph ) – Feeder graphs produced by pandapower_to_feeders()
-Returns:
-One dict per feeder with keys n_nodes n_edges max_hop is_tree total_load_mw total_gen_mw node_types
-Return type:
-list[dict]
-
-
-
-
-
-powergrid_synth.distribution.distribution_converter. pandapower_to_feeders ( net ) [source]
-Convert a pandapower network to a list of Schweitzer-format feeder graphs.
-Each connected component with at least three nodes is returned as a
-separate graph annotated with the attributes expected by
-fit_params_from_feeders() SchweetzerFeederGenerator
-
-Node attributes : h P_mw node_type 'load' 'injection' 'intermediate' pf
Edge attributes : length_km
-The function handles lines, transformers, and closed bus–bus switches
-so that the full connectivity of the pandapower network is captured.
-
-Parameters:
-net (pandapowerNet ) – A pandapower network object.
-Returns:
-One feeder graph per connected component (≥ 3 nodes).
-Return type:
-list[nx.Graph]
-
-
-
-
-
-powergrid_synth.distribution.distribution_converter. pypowsybl_to_feeders ( network ) [source]
-Convert a pypowsybl Network to a list of Schweitzer-format feeder graphs.
-This is the pypowsybl counterpart of pandapower_to_feeders() fit_params_from_feeders() SchweetzerFeederGenerator
-
-Parameters:
-network (pypowsybl.network.Network ) – A pypowsybl Network object (loaded from CGMES, XIIDM, MATPOWER, etc.).
-Returns:
-One feeder graph per connected component (≥ 3 nodes), with the
-same node/edge attributes as pandapower_to_feeders()
-Return type:
-list[nx.Graph]
-
-
-
-
-
-
-Graph Classes
-
-
-class powergrid_synth. PowerGridGraph ( * args backend = None ** kwargs ) [source]
-Bases: Graph
-Custom NetworkX Graph for Power Grids.
-Extends nx.Graph to support subgraph extraction by voltage level.
-
-
-level ( voltage_level ) [source]
-Returns a subgraph view containing only nodes at the specified voltage level.
-
-Parameters:
-voltage_level (int ) – The voltage level index (e.g., 0, 1).
-Returns:
-A subgraph view of the grid.
-Return type:
-nx.Graph
-
-
-
-
-
-
-
-class powergrid_synth. TransmissionGrid ( * args backend = None ** kwargs ) [source]
-Bases: PowerGridGraph
-Graph representation of a transmission-level power grid.
-Inherits from PowerGridGraph
-
-
-property n_levels : int
-Number of distinct voltage levels.
-
-Return type:
-int
-
-
-
-
-
-property voltage_levels : list [ int ]
-Sorted list of distinct voltage levels present in the grid.
-
-Return type:
-list[int]
-
-
-
-
-
-
-
-class powergrid_synth. DistributionGrid ( * args backend = None ** kwargs ) [source]
-Bases: PowerGridGraph
-Graph representation of a radial distribution feeder.
-Inherits from PowerGridGraph
-
-
-classmethod from_nx ( G ) [source]
-Create a DistributionGrid from any NetworkX graph.
-All node, edge, and graph attributes are copied.
-
-Parameters:
-G (Graph )
-Return type:
-DistributionGrid
-
-
-
-
-
-property is_radial : bool
-True if the graph is a connected tree.
-
-Return type:
-bool
-
-
-
-
-
-property max_hop : int
-Maximum hop distance in the feeder.
-
-Return type:
-int
-
-
-
-
-
-nodes_at_hop ( h ) [source]
-Return list of nodes at the given hop distance.
-
-Parameters:
-h (int )
-Return type:
-list
-
-
-
-
-
-nodes_by_type ( node_type ) [source]
-Return list of nodes with the given node_type
-
-Parameters:
-node_type (str ) – One of 'load' 'injection' 'intermediate'
-Return type:
-list
-
-
-
-
-
-property root
-Return the root node (hop distance 0).
-
-
-
-
-property total_gen_mw : float
-Total real-power generation (MW) across all injection nodes.
-
-Return type:
-float
-
-
-
-
-
-property total_load_mw : float
-Total real-power load (MW) across all load nodes.
-
-Return type:
-float
-
-
-
-
-
-
-
-Analysis, Export & Visualisation
-
-
-class powergrid_synth. GraphComparator ( synth_graph ref_graph synth_label = 'Synthetic' ref_label = 'Reference (Real)' ) [source]
-Bases: object
-Compares a synthetic power grid against a reference (real-world) graph.
-Provides tabular metric comparisons and visual distribution overlaps,
-both globally and per voltage level.
-
-Parameters:
-
-synth_graph (Graph )
ref_graph (Graph )
synth_label (str )
ref_label (str )
-
-
-
-compare_degree_distributions ( show_pvalue = False ) [source]
-Computes Kolmogorov-Smirnov (KS) and Relative Hausdorff (RH) statistics
-between the degree distributions of the synthetic and reference graphs,
-per voltage level. Prints and returns the results table.
-
-Parameters:
-show_pvalue (bool ) – If True, include the KS p-value column. Default False.
-Returns:
-pd.DataFrame with columns Level, KS Statistic, RH Distance
-(and KS p-value if show_pvalue is True).
-Return type:
-DataFrame
-
-
-
-
-
-plot_all_levels_comparison ( log_scale = True ) [source]
-Plots degree comparison for all common voltage levels in a single figure.
-
-Parameters:
-log_scale (bool )
-
-
-
-
-
-plot_degree_comparison ( synth_graph = None ref_graph = None ax = None log_scale = True fig_size = (8, 5) show_lines = False title = 'Degree Distribution Comparison' ) [source]
-Plots overlaid degree distributions.
-
-Parameters:
-
-synth_graph (Graph | None ) – Custom synthetic graph (or None for self.synth_graph).
ref_graph (Graph | None ) – Custom reference graph (or None for self.ref_graph).
ax (Axes | None ) – Matplotlib axis to plot on. If None, creates new figure.
log_scale (bool ) – Whether to use log-log scale (default True).
title (str ) – Title for the plot.
fig_size (Tuple )
show_lines (bool )
-
-
-
-
-
-plot_level_topology_comparison ( figsize = (15, 10) ) [source]
-Plots side-by-side bar comparisons for topology metrics per voltage level:
-Nodes, Edges, Diameter, Avg Path Length, Avg Clustering.
-
-Parameters:
-figsize (Tuple [ int , int ] )
-
-
-
-
-
-print_level_metrics ( ) [source]
-Iterates through voltage levels found in both graphs and prints metrics.
-Does NOT plot.
-
-
-
-
-print_metric_comparison ( synth_graph = None ref_graph = None title = 'GRAPH COMPARISON REPORT' ) [source]
-Prints a side-by-side table of topological metrics.
-
-Parameters:
-
-
-
-
-
-
-
-run_full_comparison ( log_scale = True ) [source]
-Runs global comparison followed by per-level comparison.
-
-Parameters:
-log_scale (bool )
-
-
-
-
-
-
-
-class powergrid_synth. GridVisualizer [source]
-Bases: object
-Visualization module for synthetic power grids.
-Allows plotting the grid with different layouts including Yifan Hu, Kamada-Kawai, and Voltage Layered.
-
-
-plot_bus_types ( graph layout = 'kamada_kawai' title = 'Bus Type Visualization' show_impedance = False figsize = (12, 10) ) [source]
-Visualizes the grid coloring nodes by their Bus Type (Static). Option to show impedance on edges.
-
-Parameters:
-
-
-
-
-
-
-
-plot_grid ( graph layout = 'kamada_kawai' title = 'Grid' show_labels = False show_bus_types = False show_impedance = False figsize = (12, 10) ) [source]
-Static plot function for grid topology.
-Options allow overlaying bus types or impedance features.
-
-Parameters:
-
-
-
-
-
-
-
-plot_impedance ( grid layout = 'kamada_kawai' title = 'Transmission Line Impedance' figsize = (12, 10) ) [source]
-Plots the grid with edges colored by their impedance magnitude (Z).
-Blue = Low Impedance (Strong), Red = High Impedance (Weak).
-
-Parameters:
-
-
-
-
-
-
-
-plot_interactive ( graph title = 'Interactive Grid' figsize = (14, 10) ) [source]
-Opens an interactive window for the full grid.
-
-Parameters:
-
-
-
-
-
-
-
-plot_interactive_bus_types ( graph title = 'Interactive Bus Type Visualization' figsize = (14, 10) ) [source]
-Opens an interactive window for Bus Type Visualization with layout selection.
-
-Parameters:
-
-
-
-
-
-
-
-plot_interactive_voltage_level ( graph level title = None figsize = (12, 10) ) [source]
-Opens an interactive window for a specific voltage level.
-
-Parameters:
-
-
-
-
-
-
-
-plot_load_gen_bubbles ( grid layout = 'kamada_kawai' title = 'Generation vs Load' show_impedance = False figsize = (12, 10) ) [source]
-Bubble plot showing generation and load magnitudes.
-Generators are blue squares, Loads are red circles.
-Size is proportional to capacity/load.
-Optionally plots impedance on edges.
-
-Parameters:
-
-
-
-
-
-
-
-plot_subgraphs ( grid layout = 'kamada_kawai' title = 'Subgraphs by Voltage Level' show_impedance = False figsize = (15, 5) ) [source]
-Plots subgraphs for each voltage level side-by-side (max 3 per row).
-
-Parameters:
-
-grid (nx.Graph ) – The main power grid graph.
layout (str ) – Layout algorithm to use.
title (str ) – Main title for the figure.
show_impedance (bool ) – Whether to color edges by impedance.
figsize (Tuple [ int , int ] ) – Base size for the figure (width, height for one row).
-Height will scale with the number of rows.
-
-
-
-
-
-
-
-class powergrid_synth. GridExporter ( graph base_mva = 100.0 base_kv_map = None ) [source]
-Bases: object
-Exports the generated synthetic grid to standard file formats via
-pandapower and pypowsybl built-in functions.
-
-Parameters:
-
-graph (Graph ) – The synthetic power grid as a NetworkX Graph.
base_mva (float ) – System base apparent power in MVA.
base_kv_map (dict | None ) – Dictionary mapping voltage level indices to kV values
-(e.g., {0: 380.0, 1: 110.0, 2: 20.0} None
-
-Example:
-exporter = GridExporter ( grid , base_mva = 100.0 ,
- base_kv_map = { 0 : 380.0 , 1 : 110.0 })
-exporter . to_json ( "output/grid.json" )
-exporter . to_excel ( "output/grid.xlsx" )
-exporter . to_pypowsybl ( "output/grid" , format = "CGMES" )
-
-
-
-to_cgmes ( filepath parameters = None ) [source]
-Export to CGMES (Common Grid Model Exchange Standard) via pypowsybl.
-
-Parameters:
-
-
-Return type:
-None
-
-
-
-
-
-to_excel ( filepath include_results = True ) [source]
-Export the grid to a pandapower Excel file.
-
-Parameters:
-
-
-Return type:
-None
-
-
-
-
-
-to_json ( filepath ) [source]
-Export the grid to a pandapower JSON file.
-
-Parameters:
-filepath (str ) – Destination file path (e.g. "output/grid.json"
-Return type:
-None
-
-
-
-
-
-to_matpower ( filepath ) [source]
-Export to MATPOWER format via pypowsybl.
-
-Parameters:
-filepath (str ) – Destination path (e.g. "output/grid"
-Return type:
-None
-
-
-
-
-
-to_pickle ( filepath ) [source]
-Export the grid to a pandapower pickle file.
-
-Parameters:
-filepath (str ) – Destination file path (e.g. "output/grid.p"
-Return type:
-None
-
-
-
-
-
-to_psse ( filepath ) [source]
-Export to PSS/E format via pypowsybl.
-
-Parameters:
-filepath (str ) – Destination path.
-Return type:
-None
-
-
-
-
-
-to_pypowsybl ( filepath format = 'XIIDM' parameters = None ) [source]
-Export the grid using pypowsybl’s built-in save.
-Supported formats: CGMES, XIIDM, MATPOWER, PSS/E, UCTE, AMPL,
-BIIDM, JIIDM.
-
-Parameters:
-
-filepath (str ) – Destination path (file or directory depending on format).
format (str ) – One of the pypowsybl export format strings.
parameters (dict | None ) – Optional format-specific parameters.
-Return type:
-None
-
-
-
-
-
-to_sqlite ( filepath include_results = False ) [source]
-Export the grid to a pandapower SQLite database.
-
-Parameters:
-
-
-Return type:
-None
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Search — PowerGridSynth 0.1.1 documentation
-
-
-
-
-
-
- PowerGridSynth
-
-
-
-
-
-
-
-
-
-
-
- Please activate JavaScript to enable the search functionality.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
`
+ * - :doc:`High-Level Synthesis `
- (recommended starting point)
- * - :doc:`Synthesis with pypowsybl `
+ * - :doc:`Synthesis with pypowsybl `
-
- * - :doc:`Topology Generation `
+ * - :doc:`Topology Generation `
- |colab_topo|
- * - :doc:`Bus Type Assignment `
+ * - :doc:`Bus Type Assignment `
- |colab_bus|
- * - :doc:`Generation and Load Settings `
+ * - :doc:`Generation and Load Settings `
- |colab_gen|
- * - :doc:`IEEE Test `
+ * - :doc:`IEEE Test `
- |colab_ieee|
- * - :doc:`PEGASE 9241 Test `
+ * - :doc:`PEGASE 9241 Test `
- |colab_pegase|
- * - :doc:`RTE 7000 Test `
+ * - :doc:`RTE 7000 Test `
- |colab_rte7k|
.. |colab_topo| image:: https://colab.research.google.com/assets/colab-badge.svg
- :target: https://colab.research.google.com/github/cookbook-ms/Chung_Lu_Chain-synthesizer/blob/main/examples/colab/TopologyGeneration_colab.ipynb
+ :target: https://colab.research.google.com/github/mshyang/GridStudio/blob/main/examples/colab/TopologyGeneration_colab.ipynb
.. |colab_bus| image:: https://colab.research.google.com/assets/colab-badge.svg
- :target: https://colab.research.google.com/github/cookbook-ms/Chung_Lu_Chain-synthesizer/blob/main/examples/colab/BusTypeAssignment_colab.ipynb
+ :target: https://colab.research.google.com/github/mshyang/GridStudio/blob/main/examples/colab/BusTypeAssignment_colab.ipynb
.. |colab_gen| image:: https://colab.research.google.com/assets/colab-badge.svg
- :target: https://colab.research.google.com/github/cookbook-ms/Chung_Lu_Chain-synthesizer/blob/main/examples/colab/GenLoadSettings_colab.ipynb
+ :target: https://colab.research.google.com/github/mshyang/GridStudio/blob/main/examples/colab/GenLoadSettings_colab.ipynb
.. |colab_ieee| image:: https://colab.research.google.com/assets/colab-badge.svg
- :target: https://colab.research.google.com/github/cookbook-ms/Chung_Lu_Chain-synthesizer/blob/main/examples/colab/ieee_test_colab.ipynb
+ :target: https://colab.research.google.com/github/mshyang/GridStudio/blob/main/examples/colab/ieee_test_colab.ipynb
.. |colab_pegase| image:: https://colab.research.google.com/assets/colab-badge.svg
- :target: https://colab.research.google.com/github/cookbook-ms/Chung_Lu_Chain-synthesizer/blob/main/examples/colab/pegase9241_test_colab.ipynb
+ :target: https://colab.research.google.com/github/mshyang/GridStudio/blob/main/examples/colab/pegase9241_test_colab.ipynb
.. |colab_rte7k| image:: https://colab.research.google.com/assets/colab-badge.svg
- :target: https://colab.research.google.com/github/cookbook-ms/Chung_Lu_Chain-synthesizer/blob/main/examples/colab/rte7k_from_source_file_colab.ipynb
+ :target: https://colab.research.google.com/github/mshyang/GridStudio/blob/main/examples/colab/rte7k_from_source_file_colab.ipynb
Here is a brief example showing how to configure the user input, and then generate, and visualize a synthetic power grid.
.. code-block:: python
:linenos:
- from powergrid_synth.generator import PowerGridGenerator
- from powergrid_synth.input_configurator import InputConfigurator
- from powergrid_synth.visualization import GridVisualizer
+ from powergrid_synth import PowerGridGenerator, InputConfigurator, GridVisualizer
# 1. Configuration
# Define the voltage levels (Node count, Avg Degree, Diameter, Distribution Type)
@@ -100,11 +98,11 @@ Distribution Grid Synthesis
* - Notebook
- Description
- * - :doc:`Distribution Feeder Synthesis `
+ * - :doc:`Distribution Feeder Synthesis `
- Schweitzer algorithm with default/custom parameters
- * - :doc:`Distribution Synthesis from Reference Grid `
+ * - :doc:`Distribution Synthesis from Reference Grid `
- Fit parameters from a pandapower network
- * - :doc:`Distribution Synthesis with pypowsybl `
+ * - :doc:`Distribution Synthesis with pypowsybl `
- Load CIGRE LV via CGMES, run full pipeline + one-liner
diff --git a/docs/index.rst b/docs/index.rst
index 2f89abd..12a4e41 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,12 +1,14 @@
-PowerGridSynth
-==============
+GridStudio
+==========
-**PowerGridSynth** is an open-source Python package for generating realistic **synthetic power grids** at both the transmission and distribution level.
+**GridStudio** is an open-source Python package for generating realistic **synthetic power grids** at both the transmission and distribution level.
- **Transmission grids** are synthesized using a `Chung-Lu-Chain (CLC) `_ graph model that reproduces prescribed degree distributions and diameters across multiple voltage levels, then layers on bus-type assignment, generation/load capacity allocation (active *and* reactive power), generation dispatch, and transmission-line impedance/capacity assignment drawn from empirical statistics of real grids (NYISO, WECC).
-- **Distribution feeders** are synthesized using the algorithm of `Schweitzer et al. (2017) `_, producing radial MV/LV tree graphs with realistic cable types, lengths, and load/generation profiles.
+- **Distribution feeders** are synthesized using the algorithm of `Schweitzer et al. (2017) `_, producing radial MV/LV tree graphs with realistic cable types, lengths, and load/generation profiles.
-Synthesised grids can be **exported to 12+ industry-standard formats** via `pandapower `_, a Linux Foundation focused on the energy sector. This project is supported by `AI-EFFECT