### Install Documentation Requirements

Source: https://github.com/powsybl/powsybl-core/blob/main/docs/README.md

Install the necessary Python packages for building the documentation. This should be done once.

```bash
pip install -r requirements.txt
```

--------------------------------

### XML Configuration Example

Source: https://github.com/powsybl/powsybl-core/blob/main/docs/user/configuration/index.md

Demonstrates the equivalent configuration structure using XML format.

```xml
<config>
    <module1>
        <property1a>value1</property1a>
        <property1b>value2</property1b>
    </module1>
    <module1>
        <property2a>value3</property2a>
        <property2b>value4</property2b>
        <property2c>value5</property2c>
    </module1>
</config>
```

--------------------------------

### Run install.sh Script

Source: https://github.com/powsybl/powsybl-core/blob/main/README.md

Execute the install.sh script to generate and install the Powsybl iTools distribution. This script compiles code and creates a standalone installation folder.

```shell
$> ./install.sh
```

--------------------------------

### Action Simulator Usage Example

Source: https://github.com/powsybl/powsybl-core/blob/main/docs/user/itools/action-simulator.md

Illustrates the general usage of the action-simulator command with common arguments and options.

```bash
usage: itools [OPTIONS] action-simulator [--apply-if-solved-violations]
       --case-file <FILE> [--contingencies <CONTINGENCY1,CONTINGENCY2,...>]
       --dsl-file <FILE> [--export-after-each-round] [--help] [-I
       <property=value>] [--import-parameters <IMPORT_PARAMETERS>]
       [--output-case-folder <CASEFOLDER>] [--output-case-format <CASEFORMAT>]
       [--output-compression-format <COMPRESSION_FORMAT>] [--output-file <FILE>]
       [--output-format <FORMAT>] [--verbose]

Available options are:
    --config-name <CONFIG_NAME>   Override configuration file name

Available arguments are:
    --apply-if-solved-violations                       apply the first tested
                                                       action which solves all
                                                       violations
    --case-file <FILE>                                 the case path
    --contingencies <CONTINGENCY1,CONTINGENCY2,...>    contingencies to test
    --dsl-file <FILE>                                  the Groovy DSL path
    --export-after-each-round                          export case after each
                                                       round
    --help                                             display the help and quit
-I <property=value>                                    use value for given
                                                       importer parameter
    --import-parameters <IMPORT_PARAMETERS>            the importer configuation
                                                       file
    --output-case-folder <CASEFOLDER>                  output case folder path
    --output-case-format <CASEFORMAT>                  output case format [CSV,
                                                       AMPL, XIIDM]
    --output-compression-format <COMPRESSION_FORMAT>   output compression format
                                                       [BZIP2, GZIP, XZ, ZIP,
                                                       ZSTD]
    --output-file <FILE>                               the output file path
    --output-format <FORMAT>                           the output file format
                                                       [JSON]
    --verbose                                          verbose mode
```

--------------------------------

### Install Powsybl Core and Powsybl HPC

Source: https://github.com/powsybl/powsybl-core/wiki/Migration-guide-v2.6.0

To create a complete iTools distribution including core and MPI capabilities, install both powsybl-core and powsybl-hpc projects to the same installation directory using the provided script or Maven commands.

```bash
$> cd powsybl-core
$> ./install --prefix=<INSTALL_DIR>
$> cd ../powsybl-hpc
$> ./install --prefix=<INSTALL_DIR>
```

```bash
$> cd powsybl-core
$> mvn install
$> cp -rp distribution-core/target/powsybl <INSTALL_DIR>
$> cd ../powsybl-hpc
$> mvn package
$> cp -rp distribution-hpc/target/powsybl <INSTALL_DIR>
```

--------------------------------

### iTools Configuration File Example

Source: https://github.com/powsybl/powsybl-core/blob/main/docs/user/itools/index.md

An example of the itools.conf file, which configures the Java Virtual Machine settings for PowSyBl. Properties like powsyl_config_name and java_xmx can be set here.

```properties
# PowSyBl configuration directories
#powsybl_config_dirs=

# PowSyBl configuration base name
powsybl_config_name=config

# Maximum size of the Java memory allocation pool
java_xmx=8G
```

--------------------------------

### Set Default Simulation Parameters (XML Example)

Source: https://github.com/powsybl/powsybl-core/blob/main/docs/simulation/dynamic/configuration.md

Example of configuring default simulation parameters including startTime, stopTime, and debugDir in XML format.

```xml
<dynamic-simulation-default-parameters>
  <startTime>0</startTime>
  <stopTime>3600</stopTime>
  <debugDir>/tmp/debugDir</debugDir>
</dynamic-simulation-default-parameters>
```

--------------------------------

### Set Default Simulation Parameters (YAML Example)

Source: https://github.com/powsybl/powsybl-core/blob/main/docs/simulation/dynamic/configuration.md

Example of configuring default simulation parameters including startTime, stopTime, and debugDir in YAML format.

```yaml
dynamic-simulation-default-parameters:
  startTime: 0
  stopTime: 3600
  debugDir: /tmp/debugDir
```

--------------------------------

### Test iTools Installation

Source: https://github.com/powsybl/powsybl-core/blob/main/docs/user/itools/index.md

Run this command in your terminal to verify that the iTools installation was successful and that the help information is displayed.

```bash
itools --help
```

--------------------------------

### YAML Configuration Example

Source: https://github.com/powsybl/powsybl-core/blob/main/docs/user/configuration/index.md

Illustrates the structure of a YAML configuration file, defining modules and their properties.

```yaml
module1:
    property1a: value1
    property1b: value2

module2:
    property2a: value3
    property2b: value4
    property2c: value5
```

--------------------------------

### Groovy Script Example

Source: https://github.com/powsybl/powsybl-core/blob/main/docs/grid_features/import_post_processor.md

An example Groovy script that prints meta-information about the imported network, such as its ID and source format.

```groovy
println "Network " + network.getId() + " (" + network.getSourceFormat()+ ") is imported"
```

--------------------------------

### CSV Output Format Example

Source: https://github.com/powsybl/powsybl-core/blob/main/docs/user/configuration/loadflow-validation.md

Example of how output data is structured when the 'output-writer' property is set to 'CSV'. Each line contains all values for a validated equipment.

```default
id;p;q;v;nominalV;reactivePowerSetpoint;voltageSetpoint;connected;regulationMode;bMin;bMax;mainComponent;validation
CSPCH.TC1;-0,00000;93,6368;238,307;225,000;0,00000;238,307;true;VOLTAGE;-0,00197531;0,00493827;true;success
CSPDO.TC1;-0,00000;0,00000;240,679;225,000;0,00000;240,713;true;VOLTAGE;-0,00493827;0,00493827;true;success
...
```

--------------------------------

### Install iTools from Sources using Maven

Source: https://github.com/powsybl/powsybl-core/blob/main/docs/user/itools/index.md

Use these Maven commands to generate the executable iTools from the powsybl-distribution sources. Ensure you checkout the latest stable release tag.

```bash
git clone https://github.com/powsybl/powsybl-distribution.git
cd powsybl-distribution
git checkout tags/<LATEST_RELEASE_TAG> -b latest-release
mvn clean package
```

--------------------------------

### Environment Variable Configuration Examples

Source: https://github.com/powsybl/powsybl-core/blob/main/docs/user/configuration/index.md

Shows how to override configuration properties using system environment variables. Module and property names are separated by double underscores.

```bash
MODULE1__PROPERTY1=1
```

```bash
LOWER_HYPHEN__PROPERTY2=2
```

```bash
LOWER_CAMEL__PROPERTY3=3
```

```bash
UPPER_CAMEL__PROPERTY4=4
```

```bash
SNAKE_CASE__PROPERTY5=5
```

--------------------------------

### Convert Network with Exporter Parameters

Source: https://github.com/powsybl/powsybl-core/blob/main/docs/user/itools/convert_network.md

This example shows how to convert a network file while providing a custom exporter configuration file and overriding a specific exporter property, such as XML indentation.

```bash
$> itools convert-network --input-file case-file.uct --output-format XIIDM --output-file case-file.xiidm --export-parameters xiidm.properties -E iidm.export.xml.indent=false
```

--------------------------------

### Configure iTools Package Maven Plugin

Source: https://github.com/powsybl/powsybl-core/blob/main/itools-packager/README.md

Example Maven configuration for the powsybl-itools-packager-maven-plugin. Customize package details, Java options, MPI settings, and file inclusions.

```xml
<build>
    <plugins>
        <plugin>
            <groupId>com.powsybl</groupId>
            <artifactId>powsybl-itools-packager-maven-plugin</artifactId>
            <version>X.X.X</version>
            <executions>
                <execution>
                    <phase>package</phase>
                    <goals>
                        <goal>package-zip</goal>
                    </goals>
                </execution>
            </executions>
            <configuration>
                <packageName>powsybl</packageName>
                <archiveName>powsybl-x-y-x</archiveName>
                <packageType>zip</packageType>
                <javaXmx>8G</javaXmx>
                <mpiTasks>2</mpiTasks>
                <mpiHosts>
                    <param>host1</param>
                    <param>host2</param>
                </mpiHosts>
                <copyToBin>
                    <files>
                        <file>...</file>
                    </files>
                </copyToBin>
                <copyToLib>
                    <files>
                        <file>...</file>
                    </files>
                </copyToLib>
                <copyToEtc>
                    <files>
                        <file>...</file>
                    </files>
                </copyToEtc>
                <copyToPackageRoot>
                    <files>
                        <file>...</file>
                    </files>
                </copyToPackageRoot>
                <licenseFile>LICENSE.txt</licenseFile>
                <thirdPartyFile>THIRD-PARTY.txt</thirdPartyFile>
            </configuration>
        </plugin>
    </plugins>
</build>

```

--------------------------------

### Default install.sh Configuration

Source: https://github.com/powsybl/powsybl-core/blob/main/README.md

The default configuration file for the install.sh script. It specifies the installation prefix and the Maven command to use.

```properties
#  -- Global options --
powsybl_prefix=$HOME/powsybl
powsybl_mvn=mvn
```

--------------------------------

### Action DSL Script Example

Source: https://github.com/powsybl/powsybl-core/blob/main/docs/user/itools/action-simulator.md

This script defines contingencies, rules, and actions for load shedding. It uses the Action DSL to specify simulation logic.

```groovy
contingency('HV_line_1') {
    equipments 'NHV1_NHV2_1'
}

contingency('HV_line_2') {
    equipments 'NHV1_NHV2_2'
}

rule('apply_shedding_for_line_1') {
    description 'Test load sheddings when line 1 is overloaded'
    life 8
    when isOverloaded(['NHV1_NHV2_1'])
    apply 'load_shed_100'
}

rule('apply_shedding_for_line_2') {
    description 'Test load sheddings when line 2 is overloaded'
    life 8
    when isOverloaded(['NHV1_NHV2_2'])
    apply 'load_shed_100'
}

action('load_shed_100') {
    description 'load shedding 100 MW'
    tasks {
        script {
            load('LOAD').p0 -= 100
        }
    }
}
```

--------------------------------

### Build Documentation (HTML with make)

Source: https://github.com/powsybl/powsybl-core/blob/main/docs/README.md

An alternative command to build the documentation in HTML format using the make utility.

```bash
make html
```

--------------------------------

### RDF Triple Example

Source: https://github.com/powsybl/powsybl-core/blob/main/docs/grid_exchange_formats/cgmes/triple_store.md

An example of a data triple in RDF/XML format, representing a subject-predicate-object relationship.

```xml
<rdf:description rdf:about="generator">
    <generator:in>France</generator:in>
</rdf:description>
```

--------------------------------

### Create and Populate Network in PowSyBl

Source: https://context7.com/powsybl/powsybl-core/llms.txt

Demonstrates creating an empty network, adding a substation, voltage levels, buses, a generator, a load, and a two-winding transformer. Includes querying network element counts and properties.

```java
import com.powsybl.iidm.network.*;

// --- Create an empty network ---
Network network = Network.create("myGrid", "test");
network.setCaseDate(ZonedDateTime.now());

// --- Add a substation ---
Substation sub = network.newSubstation()
        .setId("S1")
        .setName("Substation 1")
        .setCountry(Country.FR)
        .setTso("RTE")
        .add();

// --- Add two voltage levels (node/breaker topology) ---
VoltageLevel vl1 = sub.newVoltageLevel()
        .setId("VL1")
        .setNominalV(400.0)         // kV
        .setTopologyKind(TopologyKind.BUS_BREAKER)
        .add();

VoltageLevel vl2 = sub.newVoltageLevel()
        .setId("VL2")
        .setNominalV(225.0)
        .setTopologyKind(TopologyKind.BUS_BREAKER)
        .add();

// --- Add buses ---
Bus bus1 = vl1.getBusBreakerView().newBus().setId("B1").add();
Bus bus2 = vl2.getBusBreakerView().newBus().setId("B2").add();

// --- Add a generator on bus1 ---
Generator gen = vl1.newGenerator()
        .setId("GEN1")
        .setEnergySource(EnergySource.NUCLEAR)
        .setMinP(0.0)
        .setMaxP(1000.0)
        .setTargetP(600.0)
        .setTargetQ(0.0)
        .setTargetV(400.0)
        .setVoltageRegulatorOn(true)
        .setBus("B1")
        .setConnectableBus("B1")
        .add();
System.out.println("Generator targetP: " + gen.getTargetP() + " MW");  // 600.0

// --- Add a load on bus2 ---
Load load = vl2.newLoad()
        .setId("LOAD1")
        .setLoadType(LoadType.UNDEFINED)
        .setP0(300.0)     // MW
        .setQ0(50.0)      // MVar
        .setBus("B2")
        .setConnectableBus("B2")
        .add();

// --- Add a two-windings transformer ---
TwoWindingsTransformer twt = sub.newTwoWindingsTransformer()
        .setId("T1")
        .setVoltageLevel1("VL1")
        .setBus1("B1")
        .setConnectableBus1("B1")
        .setRatedU1(400.0)
        .setVoltageLevel2("VL2")
        .setBus2("B2")
        .setConnectableBus2("B2")
        .setRatedU2(225.0)
        .setR(0.5)     // Ω
        .setX(20.0)    // Ω
        .setG(0.0)
        .setB(0.0)
        .add();

// --- Query the network ---
System.out.println("Substations  : " + network.getSubstationCount());    // 1
System.out.println("VoltageLevels: " + network.getVoltageLevelCount());   // 2
System.out.println("Generators   : " + network.getGeneratorCount());      // 1
System.out.println("Load P0      : " + network.getLoad("LOAD1").getP0()); // 300.0
```

--------------------------------

### JSON Contingencies List Example

Source: https://github.com/powsybl/powsybl-core/blob/main/docs/user/itools/security-analysis.md

A minimal example of a contingencies list in JSON format. This can be used with the --contingencies-file option.

```json
{
  "type" : "default",
  "version" : "1.0",
  "name" : "list",
  "contingencies" : [{
    "id" : "contingency1",
    "elements" : [ {
      "id" : "id1",
      "type" : "BRANCH"
    }]
  }]
}
```

--------------------------------

### Perform Network Reduction with Default Settings

Source: https://github.com/powsybl/powsybl-core/blob/main/docs/grid_features/extraction.md

This example demonstrates how to load a network and then reduce it using the `NetworkReducer`. It includes setting a network predicate for nominal voltages and enabling boundary line replacements.

```java
Network network = Importers.loadNetwork("network.xiidm");

NetworkReducer reducer = NetworkReducer.builder()
        .withNetworkPredicate(new NominalVoltageNetworkPredicate(225.0, 400.0))
        .withBoundaryLines(true)
        .build();
reducer.reduce(network);
```

--------------------------------

### Formatted Text Output Example

Source: https://github.com/powsybl/powsybl-core/blob/main/docs/user/functional_logs/export.md

An example of the formatted text output for a report node, showing tree hierarchy with '+' and indentation.

```text
+ template with typed value
   template with several untyped first untyped value, second untyped value
```

--------------------------------

### Action Simulator Command and Output

Source: https://github.com/powsybl/powsybl-core/blob/main/docs/user/itools/action-simulator.md

This example shows the command to run the Action Simulator with a case file and a DSL script, followed by the simulation output detailing violations and applied actions.

```shell
$> itools action-simulator --case-file $HOME/eurostag-tutorial.xiidm --dsl-file $HOME/actions.groovy
Loading network '$HOME/eurostag-tutorial.xiidm'
Loading DSL 'file:$HOME/actions.groovy'
Using 'loadflow' rules engine
Starting pre-contingency analysis
    Round 0
        No more violation
Starting post-contingency 'HV_line_1' analysis
    Round 0
        Violations:
+---------------+-------+---------+--------------+----------------+-----------------+-----------+----------+------------------+----------------+
| Equipment (2) | End   | Country | Base voltage | Violation type | Violation name  | Value     | Limit    | abs(value-limit) | Loading rate % |
+---------------+-------+---------+--------------+----------------+-----------------+-----------+----------+------------------+----------------+
| NHV1_NHV2_2   | VLHV1 | FR      |          380 | CURRENT        | Permanent limit | 1008.9287 | 500.0000 |         508.9287 |         201.79 |
| NHV1_NHV2_2   | VLHV2 | FR      |          380 | CURRENT        | Permanent limit | 1047.8258 | 500.0000 |         547.8258 |         209.57 |
+---------------+-------+---------+--------------+----------------+-----------------+-----------+----------+------------------+----------------+
        Rule 'apply_shedding_for_line_2' evaluated to TRUE
        Applying action 'load_shed_100'
    Round 1
        Violations:
+---------------+-------+---------+--------------+----------------+-----------------+----------+----------+------------------+----------------+
| Equipment (2) | End   | Country | Base voltage | Violation type | Violation name  | Value    | Limit    | abs(value-limit) | Loading rate % |
+---------------+-------+---------+--------------+----------------+-----------------+----------+----------+------------------+----------------+
| NHV1_NHV2_2   | VLHV1 | FR      |          380 | CURRENT        | Permanent limit | 831.3489 | 500.0000 |         331.3489 |         166.27 |
| NHV1_NHV2_2   | VLHV2 | FR      |          380 | CURRENT        | Permanent limit | 871.7283 | 500.0000 |         371.7283 |         174.35 |
+---------------+-------+---------+--------------+----------------+-----------------+----------+----------+------------------+----------------+
        Rule 'apply_shedding_for_line_2' evaluated to TRUE
        Applying action 'load_shed_100'
    Round 2
        Violations:
+---------------+-------+---------+--------------+----------------+-----------------+----------+----------+------------------+----------------+
| Equipment (2) | End   | Country | Base voltage | Violation type | Violation name  | Value    | Limit    | abs(value-limit) | Loading rate % |
+---------------+-------+---------+--------------+----------------+-----------------+----------+----------+------------------+----------------+
| NHV1_NHV2_2   | VLHV1 | FR      |          380 | CURRENT        | Permanent limit | 667.6796 | 500.0000 |         167.6796 |         133.54 |
| NHV1_NHV2_2   | VLHV2 | FR      |          380 | CURRENT        | Permanent limit | 711.4252 | 500.0000 |         211.4252 |         142.29 |
+---------------+-------+---------+--------------+----------------+-----------------+----------+----------+------------------+----------------+
        Rule 'apply_shedding_for_line_2' evaluated to TRUE
        Applying action 'load_shed_100'
    Round 3
        Violations:
+---------------+-------+---------+--------------+----------------+-----------------+----------+----------+------------------+----------------+
| Equipment (2) | End   | Country | Base voltage | Violation type | Violation name  | Value    | Limit    | abs(value-limit) | Loading rate % |
+---------------+-------+---------+--------------+----------------+-----------------+----------+----------+------------------+----------------+
| NHV1_NHV2_2   | VLHV1 | FR      |          380 | CURRENT        | Permanent limit | 516.0706 | 500.0000 |          16.0706 |         103.21 |
| NHV1_NHV2_2   | VLHV2 | FR      |          380 | CURRENT        | Permanent limit | 566.1081 | 500.0000 |          66.1081 |         113.22 |
+---------------+-------+---------+--------------+----------------+-----------------+----------+----------+------------------+----------------+
```

--------------------------------

### Build Documentation (LaTeX PDF)

Source: https://github.com/powsybl/powsybl-core/blob/main/docs/README.md

Build the documentation in LaTeX format and then compile it to a PDF.

```bash
make latexpdf
```

--------------------------------

### CSV_MULTILINE Output Format Example

Source: https://github.com/powsybl/powsybl-core/blob/main/docs/user/configuration/loadflow-validation.md

Example of how output data is structured when the 'output-writer' property is set to 'CSV_MULTILINE'. Equipment values are split across multiple lines.

```default
id;characteristic;value
CSPCH.TC1;p;-0,00000
CSPCH.TC1;q;93,6368
CSPCH.TC1;v;238,307
...
```

--------------------------------

### IIDM Export Configuration Example

Source: https://github.com/powsybl/powsybl-core/blob/main/docs/grid_exchange_formats/iidm/export.md

Example of a YAML configuration snippet to set the default IIDM export version. This parameter applies to all IIDM formats (XML, JSON, binary).

```yaml
import-export-parameters-default-value:
  iidm.export.xml.version: 1.12
```

--------------------------------

### JSON Actions Definition Example

Source: https://github.com/powsybl/powsybl-core/blob/main/docs/user/itools/security-analysis.md

Example of a JSON file defining available actions. These actions can be referenced by operator strategies using their 'actionIds' and are specified using the --actions-file option.

```json
{
  "version" : "1.2",
  "actions" : [ {
    "type" : "TERMINALS_CONNECTION",
    "id" : "closeLine",
    "elementId" : "elementId",
    "open" : false
  } ]
}
```

--------------------------------

### Build Documentation (HTML with Cache Clear)

Source: https://github.com/powsybl/powsybl-core/blob/main/docs/README.md

Build the documentation in HTML format, clearing the Sphinx cache with the -E option if the build fails.

```bash
sphinx-build -a -E . _build/html
```

--------------------------------

### JSON Operator Strategies Example

Source: https://github.com/powsybl/powsybl-core/blob/main/docs/user/itools/security-analysis.md

Example of a JSON file defining operator strategies. These strategies are sets of conditional actions triggered in a contingency context and can be provided via the --strategies-file option.

```json
{
  "version" : "1.2",
  "operatorStrategies" : [ {
    "id" : "strategy_gen_load",
    "contingencyContextType" : "SPECIFIC",
    "contingencyId" : "contingency1",
    "conditionalActions" : [ {
      "id" : "stage1",
      "condition" : {
        "type" : "TRUE_CONDITION"
      },
      "actionIds" : [ "load-action-id", "generator-action-id" ]
    } ]
  } ]
}
```

--------------------------------

### PSSE Minimum RAWX Case Example in JSON

Source: https://github.com/powsybl/powsybl-core/blob/main/docs/grid_exchange_formats/psse/examples.md

This snippet represents the same minimal network model as the RAW example, but in a structured JSON format. It is useful for programmatic access and manipulation of network data.

```json
{
     "network":{
         "caseid":{
             "fields":["ic", "sbase", "rev", "xfrrat", "nxfrat", "basfrq", "title1"],
             "data":[0, 100.00, 35, 0, 0, 60.00, "PSS(R)E Minimum RAWX Case"]
         },
         "bus":{
             "fields":["ibus", "name", "baskv", "ide"],
             "data":[
                 [1, "Slack-Bus", 138.0, 3],
                 [2, "Load-Bus", 138.0 1]
             ]
         },
         "load":{
             "fields":["ibus", "loadid", "stat", "pl", "ql"],
             "data":[
                 [2, "1", 1, 40.0, 15.0]
             ]
         },
         "generator":{
             "fields":["ibus", "machid", "pg", "qg"],
             "data":[
                 [1, "1", "40.35", "10.87"]
             ]
         },
         "acline":{
             "fields":["ibus", "jbus", "ckt", "rpu", "xpu", "bpu"],
             "data":[
                 [1, 2, "1", 0.01938, 0.05917, 0.05280]
             ]
         }
    }
}

```

--------------------------------

### Build Documentation (HTML)

Source: https://github.com/powsybl/powsybl-core/blob/main/docs/README.md

Build the documentation in HTML format using sphinx-build. The -a flag rebuilds all files.

```bash
sphinx-build -a . _build/html
```

--------------------------------

### Configure install.sh to Use Maven Wrapper

Source: https://github.com/powsybl/powsybl-core/blob/main/README.md

Instruct the install.sh script to use the Maven Wrapper executable by specifying the --mvn option with the path to the wrapper script.

```shell
./install.sh clean --mvn ./mvnw
```

--------------------------------

### Hello World script execution

Source: https://github.com/powsybl/powsybl-core/blob/main/docs/user/itools/run-script.md

Demonstrates running a simple Groovy script that prints a greeting. Script arguments are accessible via the `args` array.

```groovy
print 'Hello ' + args[0]
```

--------------------------------

### Get Substation Coordinates

Source: https://github.com/powsybl/powsybl-core/blob/main/docs/grid_model/extensions.md

Retrieves the geographical coordinates (latitude and longitude) of a substation using its extension.

```java
Coordinate stationCoordinate = network.getSubstation("P1").getExtension(SubstationPosition.class)
    .getCoordinate();
```

--------------------------------

### Resource Bundle Property File

Source: https://github.com/powsybl/powsybl-core/blob/main/docs/user/functional_logs/index.md

Example of a resource bundle property file used for translations and message templating.

```properties
translationKey = Import file ${filename} in ${time} ms
task1 = Doing first task with double parameter ${parameter}
task2 = Doing second task, reading ${count} elements, among which ${problematicCount} are problematic
problematic = Problematic element ${id} with active power ${activePower}
```

--------------------------------

### Create Node/Breaker Voltage Level Model in Java

Source: https://context7.com/powsybl/powsybl-core/llms.txt

Demonstrates creating a voltage level with a node/breaker topology, adding busbars, breakers, disconnectors, and a generator. It also shows how to compute internal connections and access different topology views.

```java
import com.powsybl.iidm.network.*;

Network network = Network.create("topology-demo", "test");
Substation sub = network.newSubstation().setId("S1").setCountry(Country.FR).add();

// --- Node/breaker voltage level ---
VoltageLevel vl = sub.newVoltageLevel()
        .setId("VL_NB")
        .setNominalV(400.0)
        .setTopologyKind(TopologyKind.NODE_BREAKER)
        .add();

VoltageLevel.NodeBreakerView nbv = vl.getNodeBreakerView();
bbv.newBusbarSection().setId("BBS1").setNode(0).add();
bbv.newBusbarSection().setId("BBS2").setNode(1).add();
bbv.newBreaker().setId("SW1").setNode1(0).setNode2(2).setOpen(false).add();
bbv.newDisconnector().setId("DIS1").setNode1(1).setNode2(2).setOpen(false).add();

// Add generator at node 3 via disconnector to node 2
bbv.newBreaker().setId("SW2").setNode1(2).setNode2(3).setOpen(false).add();
vl.newGenerator()
        .setId("GEN_NB")
        .setNode(3)
        .setMinP(0).setMaxP(500).setTargetP(300)
        .setTargetV(400).setVoltageRegulatorOn(true)
        .add();

// --- Compute internal connections ---
int internalConnectionCount = nbv.getInternalConnectionCount();
System.out.println("Internal connections: " + internalConnectionCount);

// --- Bus/breaker view of the node/breaker model (calculated) ---
VoltageLevel.BusBreakerView bbv = vl.getBusBreakerView();
bbv.getBusStream().forEach(bus ->
    System.out.println("Calculated bus: " + bus.getId() + " (connected components)"));

// --- Bus-only view (most aggregated) ---
VoltageLevel.BusView bv = vl.getBusView();
bv.getBusStream().forEach(bus ->
    System.out.printf("Bus %s: V=%.2f kV, angle=%.4f deg%n",
            bus.getId(), bus.getV(), bus.getAngle()));
```

--------------------------------

### Link to External Documentation Page

Source: https://github.com/powsybl/powsybl-core/blob/main/docs/README.md

Examples of how to create links to entire pages in external documentation using the {doc} directive.

```Markdown
- {doc}`sphinx:usage/extensions/intersphinx`
- {doc}`Intersphinx <sphinx:usage/extensions/intersphinx>`
```

--------------------------------

### Execute a Groovy script with arguments

Source: https://github.com/powsybl/powsybl-core/blob/main/docs/user/itools/run-script.md

Shows how to execute the `hello.groovy` script with 'John' as an argument, demonstrating argument passing.

```bash
$> itools run-script hello.groovy John
Hello John
```

--------------------------------

### JSON Report Node Structure (v3.0)

Source: https://github.com/powsybl/powsybl-core/blob/main/docs/user/functional_logs/export.md

An example of the JSON structure for a report node, version 3.0, including dictionaries and the report root.

```json
{
  "version" : "3.0",
  "dictionaries" : {
    "default" : {
      "key1" : "template with typed ${value1}",
      "key2" : "template with several untyped ${value1}, ${value2}"
    }
  },
  "reportRoot" : {
    "messageKey" : "key1",
    "values" : {
      "value1" : {
        "value" : "value",
        "type" : "FILENAME"
      }
    },
    "children" : [ { 
      "messageKey" : "key2",
      "values" : {
        "value1" : {
          "value" : "first untyped value"
        },
        "value2" : {
          "value" : "second untyped value"
        }
      }
    } ]
  }
}
```

--------------------------------

### Create and Copy Default iTools Configuration

Source: https://github.com/powsybl/powsybl-core/blob/main/docs/user/itools/index.md

This command sequence creates the .itools directory in your home folder and copies the default config.yml file into it. This is useful for setting up a default configuration.

```bash
mkdir <HOME>/.itools
cp <INSTALL_DIR>/resources/config/config.yml <HOME>/.itools/config.yml
```

--------------------------------

### Execute a load flow script with input and output files

Source: https://github.com/powsybl/powsybl-core/blob/main/docs/user/itools/run-script.md

Demonstrates running the `loadflow.groovy` script, specifying the input and output file paths for the network data.

```bash
$> itools run-script loadflow.groovy XIIDM /tmp/case.xiidm /tmp/case-lf.xiidm
```

--------------------------------

### Uncompressed JSON Data Chunk Example

Source: https://github.com/powsybl/powsybl-core/blob/main/docs/data/timeseries.md

Illustrates the structure of an uncompressed JSON data chunk for time series, including offset and values.

```json
{
  "offset" : 0,
  "values" : [ 1.0, 1.0, 1.0, 3.0 ]
}
```

--------------------------------

### XML Configuration for Load Flow Action Simulator

Source: https://github.com/powsybl/powsybl-core/blob/main/docs/user/configuration/load-flow-action-simulator.md

Example XML configuration for the load-flow-action-simulator. This shows the equivalent settings to the YAML configuration, including copy strategy, debug mode, pre-contingency violation handling, load flow name, and maximum iterations.

```xml
<load-flow-action-simulator>
    <copy-strategy>STATE</copy-strategy>
    <debug>false</debug>
    <ignore-pre-contingency-violations>false</ignore-pre-contingency-violations>
    <load-flow-name>Mock</load-flow-name>
    <max-iterations>10</max-iterations>
</load-flow-action-simulator>
```

--------------------------------

### Ratio Tap Changer in Voltage Control Mode (XIIDM)

Source: https://github.com/powsybl/powsybl-core/wiki/IIDM-‐-XIIDM-‐-JIIDM-1.12-evolutions

Example of a ratio tap changer configured for voltage control mode in XIIDM.

```xml
<iidm:ratioTapChanger lowTapPosition="0" tapPosition="1" targetDeadband="0.0" loadTapChangingCapabilities="true" regulating="true" regulationMode="VOLTAGE" regulationValue="158.0">
    <iidm:terminalRef id="NHV2_NLOAD" side="TWO"/>
    <iidm:step r="0.0" x="0.0" g="0.0" b="0.0" rho="0.85"/>
    <iidm:step r="0.0" x="0.0" g="0.0" b="0.0" rho="1.00"/>
    <iidm:step r="0.0" x="0.0" g="0.0" b="0.0" rho="1.15"/>
</iidm:ratioTapChanger>
```

--------------------------------

### Retrieve CGMES Conversion Context

Source: https://github.com/powsybl/powsybl-core/blob/main/docs/grid_exchange_formats/cgmes/import.md

Get the CgmesConversionContextExtension to validate the mapping between CGMES and IIDM. This extension is present if the `iidm.import.cgmes.store-cgmes-conversion-context-as-network-extension` property is set to true.

```java
CgmesConversionContextExtension cgmesConversionContext = network.getExtension(CgmesConversionContextExtension.class);
NamingStrategy namingStrategy = cgmesConversionContext.getContext().namingStrategy();
```

--------------------------------

### Check Maven Wrapper Version

Source: https://github.com/powsybl/powsybl-core/blob/main/README.md

Verify the Maven Wrapper configuration and installation by checking its version. Set MVNW_VERBOSE=true for more detailed output if issues arise.

```shell
./mvnw -version
```

--------------------------------

### Display help for run-script command

Source: https://github.com/powsybl/powsybl-core/blob/main/docs/user/itools/run-script.md

Shows the usage and available options for the `run-script` command.

```bash
$> itools run-script --help
usage: itools [OPTIONS] run-script --file <FILE> [--help] 

Available options are:
    --config-name <CONFIG_NAME>   Override configuration file name

Available arguments are:
    --file <FILE>   the script file
    --help          display the help and quit
```