diff --git a/README.md b/README.md index 1fba0ac5..95f4c3f0 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,11 @@ # MUSE2 +## Overview + +> :warning: **Please note that MUSE2 currently only works with simple models and is not yet suitable +for use in research.** :warning: + MUSE2 (**M**od**U**lar energy systems **S**imulation **E**nvironment) is a tool for running simulations of energy systems, written in Rust. Its purpose is to provide users with a framework to simulate pathways of energy system transition, usually in the context of climate change mitigation. @@ -18,15 +23,15 @@ It is the successor to [MUSE], which is written in Python. It was developed foll MUSE to address a range of legacy issues that are challenging to address via upgrades to the existing MUSE framework, and to implement the framework in the high-performance Rust language. -Please note that MUSE2 currently only works with simple models and is not yet suitable for use in -research. +[MUSE]: https://github.com/EnergySystemsModellingLab/MUSE_OS -To download the latest version of MUSE2 for your platform, please visit [the releases page]. +## Getting started -[MUSE]: https://github.com/EnergySystemsModellingLab/MUSE_OS -[the releases page]: https://github.com/EnergySystemsModellingLab/MUSE2/releases +For information on getting started with MUSE2, please consult [the documentation]. + +[the documentation]: https://energysystemsmodellinglab.github.io/MUSE2/ -## Model Overview +## Description of model MUSE is an [Integrated Assessment Modelling] framework that is designed to enable users to create and apply an agent-based model to simulate a market equilibrium on a set of user-defined @@ -45,21 +50,6 @@ foresight over the whole modelled time horizon. [TIMES]: https://iea-etsap.org/index.php/etsap-tools/model-generators/times [MESSAGEix]: https://docs.messageix.org/en/latest -## Getting started - -The easiest way to install MUSE2 is to download the latest version for your platform on [our -releases page]. For information on getting started, please consult [the documentation]. - -If you wish to develop MUSE2 or build it from source, please see [the developer guide]. - -You can also install the [`muse2` crate from crates.io][muse2-crate], though this installation -method is only recommended for developers. - -[our releases page]: https://github.com/EnergySystemsModellingLab/MUSE2/releases -[the documentation]: https://energysystemsmodellinglab.github.io/MUSE2/ -[the developer guide]: https://energysystemsmodellinglab.github.io/MUSE2/developer_guide/ -[muse2-crate]: https://crates.io/crates/muse2 - ## Citing this repository If you use MUSE2 in your work, please cite us. For information on how to cite this repository, see diff --git a/docs/README.md b/docs/README.md index 4ed7b6a0..77f8ea8a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,18 +1,42 @@ -# Introduction +# MUSE2 -MUSE2 is a tool for running simulations of energy systems, written in Rust. It is a slimmer and -faster version of [the older MUSE tool]. To get started, please look at the [user guide] -and the [command line help]. +## Overview -For an overview of the model, see the [model description] and the [dispatch optimisation -formulation]. For a list of relevant terms, see the [glossary]. +> ⚠️ **Please note that MUSE2 currently only works with simple models and is not yet suitable +for use in research.** ⚠️ -If you are a developer, please see the [developer guide]. +MUSE2 (**M**od**U**lar energy systems **S**imulation **E**nvironment) is a tool for running +simulations of energy systems, written in Rust. Its purpose is to provide users with a framework to +simulate pathways of energy system transition, usually in the context of climate change mitigation. -[the older MUSE tool]: https://github.com/EnergySystemsModellingLab/MUSE_OS +It is the successor to [MUSE], which is written in Python. It was developed following re-design of +MUSE to address a range of legacy issues that are challenging to address via upgrades to the +existing MUSE framework, and to implement the framework in the high-performance Rust language. + +[MUSE]: https://github.com/EnergySystemsModellingLab/MUSE_OS + +## Getting started + +You will first need to install MUSE2. We recommend downloading the latest version for your platform +on [the releases page]. The archive file you download should contain a readme file containing +instructions on how to run MUSE2. Alternatively, you can install the [`muse2` crate from +crates.io][muse2-crate] using [`cargo`] (see [Setting up your development environment][dev-setup]). + +Once you have installed MUSE2, you can look at the [user guide] and the [command line help] for +details on how to get started with creating and running your own models. + +Detailed information about the model used by MUSE2 is provided in [Model Description]. For a list of +relevant terms, see the [glossary]. + +If you want to work with the MUSE2 source code, for instance to submit a change to this repository, +please see the [developer guide]. + +[the releases page]: https://github.com/EnergySystemsModellingLab/MUSE2/releases +[`cargo`]: https://doc.rust-lang.org/cargo/ +[dev-setup]: ./developer_guide/setup.md +[muse2-crate]: https://crates.io/crates/muse2 [user guide]: ./user_guide.md [command line help]: ./command_line_help.md -[model description]: ./model/ -[dispatch optimisation formulation]: ./model/dispatch_optimisation.md +[Model Description]: ./model/ [glossary]: ./glossary.md [developer guide]: ./developer_guide/