From e1ad8dd4cee445df7b84560d2b986e0fb2507b72 Mon Sep 17 00:00:00 2001
From: hzhang <hzhang@hangman-lab.top>
Date: Thu, 12 Dec 2024 09:10:26 +0000
Subject: [PATCH] add: add readme and license

---
 README.md | 144 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 license   |  22 +++++++++
 2 files changed, 166 insertions(+)
 create mode 100644 README.md
 create mode 100644 license

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..6358a5e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,144 @@
+# VirtualChemistry
+
+VirtualChemistry is a simulation framework. It is designed to model a fictional chemical reaction mechanism, including concepts analogous to atoms, bond structures, and homogeneous/heterogeneous mixtures in real chemistry.
+
+## Table of Contents
+
+- [Features](#features)
+    - [Current Features](#current-features)
+    - [Planned Features](#planned-features)
+- [Prerequisites](#prerequisites)
+- [Usage](#usage)
+    - [Installation](#installation)
+    - [Examples](#examples)
+- [License](#license)
+
+## Features
+
+### Current Features
+
+- Methods to manipulate bonds, atoms, compounds (molecules), homogeneous mixtures, and heterogeneous mixtures.
+- Methods to manipulate environments (e.g., temperature, container volume).
+
+### Planned Features
+
+- A fast mode for reactions to improve computation speed by discarding structural information of compounds.
+- Support for custom reaction mechanisms and chemistry systems.
+- Meta-reaction mode (discard the process of heat exchange and volume updates of reactions; reactions no longer need an environment or a container, just input mixtures).
+
+## Prerequisites
+
+- **.NET SDK 6.0 or 8.0**
+- [Skeleton][sk]
+
+## Usage
+
+### Installation
+
+Clone the repository to your local machine:
+
+```bash
+git clone https://git.hangman-lab.top/hzhang/VirtualChemistry.git
+cd VirtualChemistry
+```
+
+Build the project using the .NET CLI:
+
+```bash
+dotnet build
+```
+
+This command compiles the source code and restores dependencies, preparing the project for execution.
+
+Alternatively, use the NuGet package manager to add the repository source:
+
+```bash
+dotnet nuget add source --name hangman-lab https://git.hangman-lab.top/api/packages/hzhang/nuget/index.json
+```
+
+After adding the source, install the package:
+
+```bash
+dotnet add package VirtualChemistry
+```
+
+### Examples
+
+#### Manually Build a Compound
+
+You can build a compound by manually connecting bonds of atoms:
+
+```csharp
+Compound Q2()
+{
+    QAtom q1 = new();
+    QAtom q2 = new();
+    q1.C();
+    q2.C();
+    BaseBond b1 = q1.NextUnconnected("m");
+    BaseBond b2 = q2.NextUnconnected("m");
+    b1.Connect(b2);
+    Compound c = q1.GrabCompound;
+    c.Amount = 1;
+    return c;
+}
+```
+
+#### Manually Build a Mixture
+
+##### Build Homogeneous Mixture by Compounds
+
+```csharp
+HomogeneousMixture Mix(params Compound[] compounds)
+{
+    HomogeneousMixture res = new();
+    foreach (Compound c in compounds)
+        res.AddCompound(c);
+    return res;
+}
+```
+
+##### Build Heterogeneous Mixture by Homogeneous Mixtures
+
+```csharp
+HeterogeneousMixture Mix(params HomogeneousMixture[] layers)
+{
+    HeterogeneousMixture res = new();
+    foreach (HomogeneousMixture layer in layers)
+        res.AddLayer(layer);
+    return res;
+}
+```
+
+#### Process Reaction of Mixture
+
+To process a reaction for a heterogeneous mixture `h`, it needs to be in a container to provide its environment:
+
+```csharp
+class Container : IChemicalContainer
+{
+    public Container(HeterogeneousMixture h) => Content = h;
+    public double Volume() => 200;
+    public HeterogeneousMixture Content { get; set; }
+    public double EnvironmentPressure { get; set; }
+    public double EnvironmentTemperature { get; set; }
+}
+h.Container = new Container(h);
+h.Container.EnvironmentTemperature = 4.4;
+```
+
+Pressure will be updated automatically by compression stiffness and volume of the container:
+
+```csharp
+h.OneStep();
+```
+
+This represents reacting `h` for $1dt$.
+
+## License
+[MIT][license] © [hzhang][author]
+
+<!-- Definitions -->
+[author]: https://hangman-lab.top
+[license]: license
+[sk]: https://git.hangman-lab.top/hzhang/Skeleton
diff --git a/license b/license
new file mode 100644
index 0000000..d78261e
--- /dev/null
+++ b/license
@@ -0,0 +1,22 @@
+(The MIT License)
+
+Copyright (c) hzhang <hzhang@hangman-lab.top>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
\ No newline at end of file