diff --git a/docs/iidm/exporter.md b/docs/iidm/exporter.md new file mode 100644 index 0000000..c9cfef8 --- /dev/null +++ b/docs/iidm/exporter.md @@ -0,0 +1,112 @@ +--- +layout: default +--- +# Write an IIDM exporter + +From Powsybl's `Exporter` interface, it is possible to add a new data serialization format +for a IIDM network. + +In order to do so, you will need to: +- Write an implementation of the `Exporter` interface and assign it a unique ID format +- Declare the new class as a service implementation with the `@AutoService` annotation +- Build your jar + +## Configuring your module + +In order to implement a new `Exporter`, add the following dependencies in your `pom.xml` file: +- `auto-service (com.google.auto.service)`: Configuration/metadata generator for `ServiceLoader`-style providers +- `powsybl-iidm-converter-api`: IIDM network import/export API + +```xml + + + com.google.auto.service + auto-service + 1.0-rc2 + + + com.powsybl + powsybl-iidm-converter-api + ${powsybl.core.version} + + +``` + +## Implementation + +As said above, you will need to write your own implementation of the `Exporter` interface and declare it as a service +implementation. Here is an empty class template of an `Exporter` implementation: + +```java +import com.powsybl.commons.datasource.DataSource; +import com.powsybl.iidm.export.Exporter; +import com.powsybl.iidm.network.Network; + +import java.util.Properties; + +@AutoService(Exporter.class) +public class MyExporter implements Exporter { + + /** + * @return the unique ID for the given format + */ + @Override + public String getFormat() { + return null; + } + + /** + * @return information about the exporter + */ + @Override + public String getComment() { + return null; + } + + /** + * @param network the IIDM network to export + * @param parameters properties specific to this exporter + * @param dataSource access to outputStream + */ + @Override + public void export(Network network, Properties parameters, DataSource dataSource) { + // business logic to export a model to a given format + } + +} +``` + +## Deployment + +### Generating jar + +Once your implementation is ready, run the following command to create your project jar: +``` +$ cd +$ mvn clean package +``` + +The jar file will be generated in `/target`. + +### Adding the format in iTools + +[iTools](../itools/index.md) allows the user to convert a network from one format to another via the +`convert-network` command line. + +You can add your custom export format to the available output formats of the command by copying the generated jar in +your powsybl distribution: +``` +$> cp target/my-exporter.jar /share/java +``` + +## Examples + +The code of a simple CSV Exporter is available in [powsybl-tutorials](https://github.com/powsybl/powsybl-tutorials) as a +complete example of this tutorial. + +To try it, clone the project and deploy as below: +``` +$ git clone https://github.com/powsybl/powsybl-tutorials.git +$ cd powsybl-tutorials/csv-exporter +$ mvn clean package +``` diff --git a/docs/iidm/importer.md b/docs/iidm/importer.md new file mode 100644 index 0000000..0100d62 --- /dev/null +++ b/docs/iidm/importer.md @@ -0,0 +1,153 @@ +--- +layout: default +--- +# Write an IIDM importer + +From Powsybl's `Importer` interface, it is possible to add a new file format from which +an IIDM data model can be loaded. + +In order to do so, you will need to: +- Write an implementation of the `Importer` interface +- Declare the new class as a service implementation with the `@AutoService` annotation +- Build your jar + +## Configuring your module + +In order to implement a new `Importer`, add the following dependencies in your `pom.xml` file: +- `auto-service (com.google.auto.service)`: Configuration/metadata generator for `ServiceLoader`-style providers +- `powsybl-iidm-converter-api`: IIDM network import/export API + +```xml + + + com.google.auto.service + auto-service + 1.0-rc2 + + + com.powsybl + powsybl-iidm-converter-api + ${powsybl.core.version} + + +``` + +## Implementation + +As said above, you will need to write your own implementation of the `Importer` interface and declare it as a service +implementation. Here is an empty class template of an `Importer` implementation: + +```java +import com.powsybl.commons.datasource.DataSource; +import com.powsybl.commons.datasource.ReadOnlyDataSource; +import com.powsybl.iidm.import_.Importer; +import com.powsybl.iidm.network.Network; +import com.powsybl.iidm.parameters.Parameter; + +import java.util.List; +import java.util.Properties; + +@AutoService(Importer.class) +public class MyImporter implements Importer { + + /** + * Get a unique identifier of the format. + * + * @return the unique ID for the given format + */ + @Override + public String getFormat() { + return null; + } + + /** + * This override is optional. By default, it returns Collections.emptyList() + * + * @return description of import parameters + */ + @Override + public List getParameters() { + return Collections.emptyList(); + } + + /** + * Get some information about this importer. + * + * @return information about the importer + */ + @Override + public String getComment() { + return null; + } + + /** + * Check if the data source is importable + * + * @param dataSource the data source + * @return true if the data source is importable, false otherwise + */ + @Override + public boolean exists(ReadOnlyDataSource dataSource) { + return false; + } + + /** + * Create a model. + * + * @param dataSource data source + * @param parameters some properties to configure the import + * @return the model + */ + @Override + public Network importData(ReadOnlyDataSource dataSource, Properties parameters) { + // business logic to import a network from a data source in a given format + return null; + } + + /** + * Copy data from one data source to another. + * + * @param fromDataSource from data source + * @param toDataSource destination data source + */ + @Override + public void copy(ReadOnlyDataSource fromDataSource, DataSource toDataSource) { + // business logic to copy a network from a data source to another file in a given format + } +} +``` + +## Deployment + +### Generating jar + +Once your implementation is ready, run the following command to create your project jar: +``` +$ cd +$ mvn clean package +``` + +The jar file will be generated in `/target`. + +### Adding the format in iTools + +[iTools](../itools/index.md) allows the user to convert a network from one format to another via the +`convert-network` command line. + +You can add your custom import format, allowing files in this format to be converted using the command, by copying the +generated jar in your powsybl distribution: +``` +$> cp target/my-exporter.jar /share/java +``` + +## Examples + +The code of a simple CSV Importer is available in [powsybl-tutorials](https://github.com/powsybl/powsybl-tutorials) as a +complete example of this tutorial. + +To try it, clone the project and deploy as below: +``` +$ git clone https://github.com/powsybl/powsybl-tutorials.git +$ cd powsybl-tutorials/csv-importer +$ mvn clean package +``` diff --git a/docs/iidm/index.md b/docs/iidm/index.md new file mode 100644 index 0000000..737e184 --- /dev/null +++ b/docs/iidm/index.md @@ -0,0 +1,12 @@ +--- +layout: default +--- +# IIDM import/export + +```{toctree} +--- +maxdepth: 2 +--- +importer.md +exporter.md +``` \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index bc3ed77..eb57c24 100644 --- a/docs/index.md +++ b/docs/index.md @@ -9,6 +9,7 @@ hidden: true --- intellij.md iTools +IIDM import/export Load flow Sensitivity analysis Topology diff --git a/docs/topology.md b/docs/topology.md index 07a9452..5957ca4 100644 --- a/docs/topology.md +++ b/docs/topology.md @@ -5,7 +5,7 @@ layout: default # How to manage topological views? This example aims first to create a substation with a node/breaker topology model and to visit it through the bus/breaker and the bus views. Then, we create the same substation with a bus/breaker topology model and we visit it through the bus/breaker and the bus views. -The corresponding code is fully available in the [topology](https://github.com/powsybl/powsybl-tutorials) tutorial. +The corresponding code is fully available in the [topology](https://github.com/powsybl/powsybl-tutorials/topology) tutorial. ## Building a network in node/breaker topology model diff --git a/itools-packager/pom.xml b/itools-packager/pom.xml index 4a1ffc7..26b2a6b 100644 --- a/itools-packager/pom.xml +++ b/itools-packager/pom.xml @@ -43,6 +43,12 @@ + + + org.slf4j + log4j-over-slf4j + runtime + ch.qos.logback logback-classic