tlaplus / communitymodules

TLA+ snippets, operators, and modules contributed and curated by the TLA+ community

Community Repository

This is an open repository dedicated to contributions from the TLA+ community. Here you can submit the snippets, operators, and modules that you wrote for your specifications and that you want to share with the rest of the TLA+ community.

(For us to gauge demand, please star (eyes up and right) this repository if you use the CommunityModules.)

The Modules

Name	Short description	Module Override?	Contributors
BagsExt.tla	Additional operators on bags (e.g. BagAdd, BagRemove, FoldBag, etc.)	✔	@muenchnerkindl, @lemmy
Bitwise.tla	Bitwise And and shift-right.	✔	@lemmy, @pfeodrippe
Combinatorics.tla	Binomial coefficient (N choose K) and factorial operator	✔	@lemmy
CSV.tla	Operations on CSV files	✔	@lemmy
DifferentialEquations.tla	see page 178 of Specifying Systems		Leslie Lamport
DyadicRationals.tla	Operations on dyadic rational numbers	✔	@lemmy
FiniteSetsExt.tla	Additional operators on finite sets (e.g. FoldSet, Min, Max, Quantify, etc.)	✔	@hwayne, @lemmy, @quicquid, @mryndzionek, @will62794, @konnov
Folds.tla	Basic Fold operator (MapThenFoldSet).		@quicquid, @muenchnerkindl, @konnov
Functions.tla	Notions about functions (range, anti-function, injection, surjection, bijection) and folds (FoldFunction, FoldFunctionOnSet).	✔	Thomas L. Rodeheffer, @muenchnerkindl, @quicquid, @lemmy
Graphs.tla	Common operators on directed and undirected graphs		Leslie Lamport, @lemmy, @muenchnerkindl
GraphViz.tla	Generate GraphViz file through TLC	✔	@lemmy
HTML.tla	Format strings into HTML tags		@afonsof
IOUtils.tla	Input/Output of TLA+ values & Spawn system commands from a spec.	✔	@lemmy, @lvanengelen, @afonsof
Json.tla	JSON serialization and deserialization into TLA+ values.	✔	@kuujo, @lemmy, @jobvs, @pfeodrippe
Relation.tla	Basic operations on relations, represented as binary Boolean functions over some set S.		@muenchnerkindl
SequencesExt.tla	Additional operators on sequences (e.g. ToSet, Reverse, ReplaceAll, SelectInSeq, etc.)	✔	@muenchnerkindl, @lemmy, @hwayne, @quicquid, @konnov, @afonsof
ShiViz.tla	Visualize error-traces of multi-process PlusCal algorithms with an Interactive Communication Graphs.		@lemmy
Statistics.tla	Statistics operators (ChiSquare, etc.)	✔	@lemmy
SVG.tla	see will62794/tlaplus_animation	✔	@will62794, @lemmy
TLCExt.tla	Assertion operators and experimental TLC features (now part of TLC).	✔	@lemmy, @will62794
VectorClocks.tla	Causal order operations on vector clocks (e.g. CausalOrder, IsCausalOrder)	✔	@lemmy

How to use it

You must be running Java 9 or higher.

Just copy & paste the snippet, the operators, or the set of modules you are interested in.

Alternatively, clone this repository and pass -DTLA-Library=/path/to/CommunityModules/modules when running TLC.

Another option is to download a library archive and add it to TLC's or the Toolbox's TLA+ library path. The advantage of doing this is that TLC will evaluate an operator faster if the operator comes with a Java implementation (see e.g. SequencesExt.Java). The latest release is at the stable URL https://github.com/tlaplus/CommunityModules/releases/latest/download/CommunityModules-deps.jar.

If you are using the Toolbox, add the library archive under File > Preferences > TLA+ Preferences > TLA+ library path locations.

If you are using the VS Code extension, a recent version of the community modules is bundled with the nightly build. If you are not using the nightly build or need to use another version, see this.

If you are running TLC via tla2tools.jar, ensure the JAR is on the classpath: either place it next to tla2tools.jar or add it explicitly with java -cp tla2tools.jar:CommunityModules-deps.jar ....

Being a community-driven repository puts the community in charge of checking the validity and correctness of submissions. The maintainers of this repository will try to keep this place in order. Still, we can't guarantee the quality of the modules and, therefore, cannot provide any assistance on eventual malfunctions.

Contributing

If you have one or more snippets, operators, or modules you'd like to share, please open an issue or create a pull request. Before submitting your operator or module, please consider adding documentation. The more documentation there is, the more likely it is that someone will find it useful.

If you change an existing module and tests start failing, check all tests that assert (usually AssertError operator) specific error messages, i.e., line numbers and module names. Note that even an unrelated change further up in the file might have changed the line number and could lead to a failing test case.

Test

Run

ant test

Download

communitymodules's Issues

TLA google group auto deleting posts and replies?

Hi folks, sry for opening an issue here.

I was trying to reply to some posts in the google group, as well as posting some new conversation. But it looks like all my messages are auto deleted.

I'm not sure why. Anyone experiencing the same?

Replace definition of `FlattenSet` with `UNION`

FlattenSet({{1},{2}}) = UNION {{1},{2}}

CommunityModules/modules/FiniteSetsExt.tla

Lines 42 to 51 in e88b553

	FlattenSet(S) ==
	(******************************************************************************)
	(* Starting from base, apply op to f(x), for all x \in S, in an arbitrary *)
	(* order. It is assumed that op is associative and commutative. *)
	(* *)
	(* Example: *)
	(* *)
	(* FlattenSet({{1},{2}}) = {1,2} *)
	(******************************************************************************)
	FoldSet(LAMBDA x,y: x \cup y, {}, S)

@konnov @Kukovec @quicquid

The latest version is incompatible with Toolbox < 1.7.1

Hello. I guess this is to be expected, but just to confirm, latest CM version fails when loaded on toolbox 1.7.0:

The exception was a java.lang.VerifyError
: class tlc2.overrides.FiniteSetsExt$KSubsetValue overrides final method tlc2.value.impl.SubsetValue.elements()Ltlc2/value/impl/ValueEnumeration;

It seems method SubsetValue.elements() was declared final before 1.7.1

EDIT: to be more precise, this is from CM 202009181838 onwards.

Add Apalache type annotations to CommunityModules

We should add type annotations to the CommunityModules where possible to (strategically) support model-checking with Apalache.

/cc @konnov

Add `SequencesExt!FirstMatch`

---- MODULE SequencesExt ----

...

FirstMatch(s, P(_)) ==
  IF { i \in 1..Len(s) : P(s[i]) } # {}
  THEN Min( { i \in 1..Len(s) : P(s[i]) } )
  ELSE 0

====

Create Rationals module

This would enable division plus floor/ceiling functions, with the following benefits:

• Calculate the size of the majority of a set (currently passed in as a constant in the Paxos spec)
• Enable specification of algorithms requiring calculating midpoint of array (binary search, sorting, etc.)

Would theoretically include Java module override with an exact-representation Rationals implementation.

Unit tests in `FiniteSetsExtTests` rely on specific line numbers

These unit tests in FiniteSetsExtTests rely on specific line numbers of statements in the FiniteSetsExt.tla module. So, if one tries to modify FiniteSetsExt.tla in a way that shifts existing statements to different line numbers, it breaks these tests. These tests should be updated to avoid dependence on specific line numbers.

Request: Add string formatting operator

String formatting overloads would make debugging easier when used in conjunction with PrintT(). I'm aware VSCode has a LLVM debugger, but the Toolbox does not... There might be other uses of which I'm not aware.

For example, we could have a TLCExt!Format(sequence) operator that converts any non-string element of a sequence to string and concatenates all of them. That might be possible in TLA⁺, but slow because the language lacks typing.

Any thoughts?

Refactor JSON module to depend on Gson instead of Jackson

The TLA+ Community Modules [1] have a JSON module [2] with which users can import and export TLA+ values to JSON. The JSON module's implementation [3] is built on Jackson/FasterXML [4]. Jackson XML is rather large in size and has an unclear license. Gson [5], on the other hand, is slimmer and comes with a compatible license. Thus, the Jackson XML dependency of Json.java should be replaced with Gson while maintaining the same functionality.

[1] https://github.com/tlaplus/CommunityModules
[2] https://github.com/tlaplus/CommunityModules/blob/master/modules/Json.tla
[3] https://github.com/tlaplus/CommunityModules/blob/master/modules/tlc2/overrides/Json.java
[4] https://github.com/FasterXML/
[5] https://github.com/google/gson

Module override for SequencesExt!Suffixes

	/*
	   Suffixes(s) ==
		  (**************************************************************************)
		  (* The set of suffixes of the sequence s, including the empty sequence.   *)
		  (**************************************************************************)
		  { SubSeq(s, l, Len(s)) : l \in 1..Len(s) } \cup {<<>>}
	 */
	@TLAPlusOperator(identifier = "Suffixes", module = "SequencesExt", warn = false)
	public static Value Suffixes(final Value s) {
		final TupleValue seq = (TupleValue) s.toTuple();
		if (seq == null) {
			throw new EvalException(EC.TLC_MODULE_ARGUMENT_ERROR,
					new String[] { "first", "Suffixes", "sequence", Values.ppr(s.toString()) });
		}
		
		final Value[] vals = new Value[seq.elems.length + 1];
		
		// \cup {<<>>} 
		vals[0] = TupleValue.EmptyTuple;
		
		// Add the elements in reverse order to implicitly normalize the SetEnumValue.
		for (int i = seq.elems.length - 1; i >= 0; i--) {
			final Value[] suffix = new Value[seq.elems.length - i];
			System.arraycopy(seq.elems, i, suffix, 0, seq.elems.length - i);
			
			vals[seq.elems.length - i] = new TupleValue(suffix);
		}
		
		// Decided against calling "normalize" as a safeguard, even though "vals" will
		// be normalized. This is because "normalize," albeit performing a single pass
		// over "vals" for a normalized input, still compares elements, which can be
		// expensive: return new SetEnumValue(vals, false).normalize();
		return new SetEnumValue(vals, true);
	}

FiniteSetsExt!Sum and FiniteSetsExt!Product easily name-clash

CommunityModules/modules/FiniteSetsExt.tla

Lines 16 to 32 in 23fbb1f

	Sum(set) ==
	(*************************************************************************)
	(* Calculate the sum of the elements in set. *)
	(* *)
	(* Example: *)
	(* Sum(0 .. 10) = 55 *)
	(*************************************************************************)
	FoldSet(+, 0, set)
	Product(set) ==
	(*************************************************************************)
	(* Calculuate the product of the elements in set. *)
	(* *)
	(* Example: *)
	(* Product(1 .. 3) = 6 *)
	(*************************************************************************)
	FoldSet(LAMBDA x, y: x * y, 1, set)

Sum -> SumSet
Product -> ProductSet

Both names would also be in line with ReduceSet.

Objections anybody?

TLCExtTest.java fails when running on Java 1.8

When running ant test (with showoutput="yes") on Java 1.8 (assuming that #31 is fixed), TLCExtTest.java fails

    [junit] Running tlc2.overrides.TLCExtTest
    [junit] TLC2 Version 2.15 of Day Month 20?? (rev: 674ca73)
    [junit] Running breadth-first search Model-Checking with fp 0 and seed 1 with 1 worker on 4 cores with 3516MB heap and 0MB offheap memory (Linux 4.15.0-128-generic amd64, Private Build 1.8.0_275 x86_64, OffHeapDiskFPSet, DiskStateQueue).
    [junit] Parsing file /home/rafael/dev/CommunityModules/tests/IncompleteStates.tla
    [junit] Parsing file /tmp/TLCExt.tla
    [junit] Parsing file /tmp/TLC.tla
    [junit] Parsing file /tmp/Naturals.tla
    [junit] Parsing file /tmp/Sequences.tla
    [junit] Parsing file /tmp/FiniteSets.tla
    [junit] Semantic processing of module Naturals
    [junit] Semantic processing of module Sequences
    [junit] Semantic processing of module FiniteSets
    [junit] Semantic processing of module TLC
    [junit] Semantic processing of module TLCExt
    [junit] Semantic processing of module IncompleteStates
    [junit] Starting... (2021-01-07 23:32:24)
    [junit] Computing initial states...
    [junit] Finished computing initial states: 1 distinct state generated at 2021-01-07 23:32:24.
    [junit] Model checking completed. No error has been found.
    [junit]   Estimates of the probability that TLC did not check all reachable states
    [junit]   because two distinct states had the same fingerprint:
    [junit]   calculated (optimistic):  val = 5.4E-20
    [junit] The coverage statistics at 2021-01-07 23:32:24
    [junit] <Init line 7, col 1 to line 7, col 4 of module IncompleteStates>: 1:1
    [junit]   line 8, col 3 to line 11, col 13 of module IncompleteStates: 1
    [junit] <Next line 13, col 1 to line 13, col 4 of module IncompleteStates>: 0:1
    [junit]   line 14, col 6 to line 14, col 19 of module IncompleteStates: 1
    [junit] End of statistics.
    [junit] 2 states generated, 1 distinct states found, 0 states left on queue.
    [junit] The depth of the complete state graph search is 1.
    [junit] The average outdegree of the complete state graph is 0 (minimum is 0, the maximum 0 and the 95th percentile is 0).
    [junit] Finished in 00s at (2021-01-07 23:32:24)
    [junit] Tests run: 1, Failures: 2, Errors: 0, Skipped: 0, Time elapsed: 0,539 sec

We can see that there is no overriding of the TLCExt by its java counterpart, so I assume that there is some difference at the loading of overriding modules between different JVMs, is this intentional?

Problem using ReplaceFirstSubSeq and ReplaceAllSubSeqs with strings

Hello, the replace operator with strings is not correctly replacing the following chars: "\n", "\t", "\f", and"\r".

For example, in the following assume expressions, the first two are true and the last four false.

ASSUME(ReplaceAllSubSeqs("\\", "%%", "Properly escape the %% quotes") = "Properly escape the \\ quotes")
ASSUME(ReplaceAllSubSeqs("\"", "%%", "Properly escape the %% quotes") = "Properly escape the \" quotes")
ASSUME(ReplaceAllSubSeqs("\n", "%%", "Properly escape the %% quotes") = "Properly escape the \n quotes")
ASSUME(ReplaceAllSubSeqs("\t", "%%", "Properly escape the %% quotes") = "Properly escape the \t quotes")
ASSUME(ReplaceAllSubSeqs("\f", "%%", "Properly escape the %% quotes") = "Properly escape the \f quotes")
ASSUME(ReplaceAllSubSeqs("\r", "%%", "Properly escape the %% quotes") = "Properly escape the \r quotes")

Some options that i found that can fix it are:

1. Not using unquote and not using Pattern.quote.

Example:
((StringValue) t).toUnquotedString(); -> ((StringValue) t).getVal().toString();
st.replaceFirst(Pattern.quote(ss), sr) -> st.replaceAll(ss, sr)
Problem:
Slash and dollar sign have to be special escaped, for example the first assume expression would have to change to:
ASSUME(ReplaceAllSubSeqs("\\\\", "%%", "Properly escape the %% quotes") = "Properly escape the \\ quotes")
However, the remain ones would work as they are.

2. Change to use functions without regex.

For replaceAll there is replace. For replaceFirst I did not find one in the standard library, however there is replaceOnce in org.apache.commons.lang3.StringUtils that can be used. There is also the option to create a custom one using find, substr and replace.

I can work on a pull request for this issue, what would be the best approach to modify ReplaceFirstSubSeq and ReplaceAllSubSeqs ?

REF

https://github.com/tlaplus/CommunityModules/blob/master/modules/tlc2/overrides/SequencesExt.java#L243
https://docs.oracle.com/javase/7/docs/api/java/lang/String.html#replace(java.lang.CharSequence,%20java.lang.CharSequence)
https://docs.oracle.com/javase/7/docs/api/java/lang/String.html#replaceAll(java.lang.String,%20java.lang.String)
https://docs.oracle.com/javase/7/docs/api/java/lang/String.html#replaceFirst(java.lang.String,%20java.lang.String)
https://commons.apache.org/proper/commons-lang/apidocs/org/apache/commons/lang3/StringUtils.html#replaceOnce-java.lang.String-java.lang.String-java.lang.String-

Bad format of Json trace printing

Hello! I learned printing a TLC error trace in #json format and tried the EWD840_json example:

sed -i '/^SendMsg/{n;d;}' EWD840.tla  # delete '/\ active[i]' below SendMsg
wget -q https://nightly.tlapl.us/dist/tla2tools.jar \
           https://modules.tlapl.us/releases/latest/download/CommunityModules-deps.jar
java -jar tla2tools.jar EWD840_json

TLC prints Error: Evaluating invariant JsonInv failed. and the traces. The trace.json file content is:

[

Is there something I made a mistake?

It seems JsonInv should not be violated since TLCSet("exit", TRUE). I replaced JsonSerialize("trace.json", Trace) with TRUE and TLC shows that JsonInv is not violated.

I tried another example DieHard, which violates the Inv big /= 4. TLC prints no trace and there is a trace.json file. I think this should be the expected behavior?

But after repeatedly running DieHard, I found the trace.json can be bad formatted:

[
{"big":0,"small":0},
{"big":5,"small":0},
{"big":2,"small":3},
{"big":2,"small":0},
{"big":0,"small":2},
{"big":5,"small":2},
{"big":4,"small":3}
]
"big":1,"small":3},
{"big":4,"small":0}
]

After trying the above, I think Json.tla might has a bug if my operations are correct.

Consider bundling CommunityModules.jar as part of a TLC release

dgpv/bip32_template_parse_tplaplus_spec#1 shows that users are reluctant to adopt CM because it adds an additional dependency. Thus, we should consider bundling/shipping a snapshot of CM with new TLC releases.

Requirements:

• Don't blur the lines between CM and the TLA+ standard modules (Specifying Systems)
• Override bundled CM with a newer release

Documentation: broken urls for TLCExt.tla

The url links for TLCExt.tla are not working (in https://github.com/tlaplus/CommunityModules/blob/master/README.md).
I think the module was moved to the main repository in https://github.com/tlaplus/tlaplus/tree/master/tlatools/org.lamport.tlatools/src/tla2sany/StandardModules

Should the url links be updated or is this module no longer a community module and should be removed from the table? Or maybe add a column to tell if it has been "graduated" to the main repo?

Add `IOUtils!IOEnv` that equals a record of all environment variables

Use cases

• Check spec for various constant values without generating model files

---- MODULE S ----
CONSTANT N
...
====

---- MODULE MC ----
EXTENDS IOUtils
NEnv == IOEnv.nSetAsEnvVarFromSomeScript
\* If "type" conversion to Integer is desired: CHOOSE n \in 1..10: ToString(n) = NEnv
...
====

---- CONFIG MC ----
CONSTANT 
N = NEnv
...
====

• Initialize TLCSet "register" for each behavior generated as part of the simulation

export T=42 && tla2tools.jar -simulate num=$T SomeSpec

---- MODULE SomeSpec ----
EXTENDS IOUtils
...
ASSUME \A i \in 1..IOEnv.T: TLCSet(i, 0)
...
Next == 
  \* Record some stats
  TLCSet(TLCGet("diameter"), TLCGet("diameter") + 1)

PostCondition ==
  \A i \in 1..IOEnv.T: TLCGet(i)
====

---

Alternative, although Apalache (@konnov) could probably "implement" IOEnv:

TLCGet("env")

---

Workaround (Linux/macOS):

IOExec(<<"printenv", "PATH">>)

For some reason, the following equals the empty string although PATH is set:

IOExec(<<"echo", "$PATH">>)
IOExec(<<"/bin/bash", "-c", "echo", "$PATH">>)

How to write my operator which can be used in TLA+

In my work, I want to enumerate all possible event structure satisfying partial order.
However, if we write TLA+ like this:

PartialOrderSubset(s) ==
    LET rels == SUBSET (s \X s)
    IN {po \in rels : IsStrictPartialOrder(po, s)}

We should enumerate all subsets, it's time costing. So I'd like to define my operator by Java and override it. I forked this repository and writes my implementation. See Update PartialOrderExt

And then, I built my CommunityModules-deps.jar and added it to TLC's or the Toolbox's TLA+ library path.
I think it will call my implementation in PartialOrderSubset.java instead of the original definition in PartialOrderSubset.tla but it didn't work. Is there anything wrong of my settings?

ChooseOne operator

I would like to propose adding ChooseOne defined as follows:

ChooseOne(S, P(_)) == CHOOSE x \in S : P(x) /\ \A y \in S : P(y) => y = x

What would be the best place to put it?

Add Fold operators for Bags.tla (in new BagsExt.tla)

@muenchnerkindl noted that we lack fold operators for the Bags.tla module. @konnov Does Apalache already have folds for bags?

Add SVG!Svg element

https://github.com/lemmy/tlaplus_specs/blob/908abbb9c3e61ba504643a4a51717cc2f854ee74/AsyncGameOfLifeAnimGlider.tla#L18-L21 shows why.

https://developer.mozilla.org/en-US/docs/Web/SVG/Element/svg

SequencesExt issue?

Description

I'm was just trying to evaluate some expressions using the Toolbox, with "No Behavior Spec" checkbox on.
I've added CommunityModules.jar and CommunityModules-deps.jar in the "TLA+ Preferences" / "Library Path Locations"

My "spec" is
EXTENDS Sequences, SequencesExt

PS. If I delete SequencesExt from the EXTENDS list, I do not get an error.

Expected Behavior

No errors

Actual Behavior

Parsing or semantic analysis failed.

Your Environment

I'm using the latest tlatoolbox and community modules, downloaded them this morning.
Operating System: Ubuntu

Add `Reduce` operator to `Functions`

Reduce(op(_,_), fun, from, to, base) == 
  (**************************************************************************)
  (* Reduce the elements in the range from..to of the function's co-domain. *)
  (**************************************************************************)
  LET reduced[i \in from..to] ==
          IF i = from THEN op(base, fun[i])
          ELSE op(reduced[i - 1], fun[i])
  IN reduced[to]

/cc @muenchnerkindl @konnov @quicquid

Add generic `Serialize` and `Deserialize` operators to `IOUtils`.

IOExec!IOSerialize serializes the given TLA+ value with Java's built-in serialization. Alternatively, IOUtils!IOExec provides a low-level mechanism to write to files (see example at the bottom). More specifically, the Json and CSV modules have dedicated serialization mechanisms.

As a long-term replacement, TLA+ should subsume serialization under:

---- MODULE IOUtils ----

Serialize(value,dest,serializer,options) ==
    (* value: TLA+ value to be serialized. *)
    (* dest: Destination to serialize to such as a file or URL. *)
    (* serializer: Identifier of the serializer to be used such as "CSV", "NDJSON", "JSON", "TXT". *)
    (* options: Record of serializer-specific options. *)
    CHOOSE r \in [exitValue : Int, stdout : STRING, stderr : STRING] : TRUE

Deserialize(src,serializer,options) ==
    CHOOSE v

====

The advantage of this high-level interface is that serialization/deserialization is independent of a particular serializer and always looks the same while allowing serializers to add additional features such as formatting:

\* Plaintext
Serialize("An ordinary TLA+ string", "file.txt", "TXT", [charset|-> "UTF-8", append |-> TRUE])

\* Java string formatting
Serialize(<<"abc", 42, {"x", "y"} >>, "file.txt", "PRINTF", [pattern |-> "%1$s#%2$s#%3$s", charset|-> "UTF-8", append |-> TRUE])

\* CSV
Serialize(<<23, 42 77, "foo", {1,2,3}>>, "file.csv", "CSV", [headers |-> <<"A", "B", "Name", "Elems">>, delimiter |-> "#", append |-> TRUE])

Variant: Serializer moved into options:

---- MODULE IOUtils ----

Serialize(value,dest,options) ==
    (* value: TLA+ value to be serialized. *)
    (* dest: Destination to serialize to such as a file or URL. *)
    (* options: Record of serializer-specific options. *)
    CHOOSE r \in [exitValue : Int, stdout : STRING, stderr : STRING] : TRUE

Deserialize(src,options) ==
    CHOOSE v

====

\* Plaintext
Serialize("An ordinary TLA+ string", "file.txt", [serializer |-> "TXT", charset|-> "UTF-8", append |-> TRUE])

Serializers will be loaded by some service loader mechanism.

---

\* This is not even platform independent.
IOExec( <<"bash", "-c",  "echo \"Some String\" > " \o "SomeFile.txt">>)

Add PlusPy's `Messaging.tla`

PlusPy introduces a (generic) Messaging module that we should move to the CommunityModules.

/cc @johnyf

Configure an github action to run the tests in the Java 1.8 environment

We don't test Java 1.8 yet in our CI, see #30 (review) for context.

This should be done after #31 and #34 are resolved.

Better compatibility with TLAPS

@muenchnerkindl Can/should we move the following two modules to TLAPS:
https://github.com/tlaplus/CommunityModules/blob/master/modules/SequencesExtTheorems.tla
https://github.com/tlaplus/CommunityModules/blob/master/modules/SequencesExtTheorems_proofs.tla

We should not move SequencesExt though because the module comes with Java module overrides.

Add `Functions!RestrictPred` (Filter)

RestrictPred(f, Test(_)) ==
    Restrict(f, { x \in DOMAIN f : Test(x) })

Could also be named Filter to align with map and fold known to functional programmers, but then we already have Restrict.

Add Java module override for `Folds`

Add Java module override for Fold!MapThenFoldSet

Teach Json module to convert a richer set of TLA+ values

After specifying a TLA+ spec I would like to export traces of behaviors so I can use them as input for generating tests of the implementation.

Let's say I have the following spec of my system:

---- MODULE Box ----
CONSTANTS ItemIds
VARIABLE items

BoxInit == items \in SUBSET ItemIds

Add(i) == items' = items \union {i}
Remove(i) == items' = items \ {i}

BoxNext == \/ \E i \in ItemIds \ items: Add(i)
           \/ \E i \in items: Remove(i)
           \/ UNCHANGED items
====

And the following utility spec:

---- MODULE BoxTrace ----
EXTENDS Box, Sequences, Json

CONSTANTS ItemIds
VARIABLE trace, json

BoxTraceInit == /\ BoxInit
                /\ trace = [init |-> items, steps |-> <<>>, state |-> items]
                /\ json = ToJsonObject(trace)

BoxTraceNext == \/ \E i \in ItemIds \ items: 
                  /\ Add(i)
                  /\ trace' = [trace EXCEPT !.steps = Append(@, [action |-> "Add", item |-> i]),
                                            !.state = items']
                  /\ json' = ToJsonObject(trace')
                \/ \E i \in items:
                  /\ Remove(i)
                  /\ trace' = [trace EXCEPT !.steps = Append(@, [action |-> "Remove", item |-> i]),
                                            !.state = items']
                  /\ json' = ToJsonObject(trace')

====

Running this in simulation mode with -simulate num=10,file=traces/trace -depth 5 BoxTrace generates trace files for different behaviors. The last state output in any of those then gives me an initial state, the actions that have been applied together with the parameters and the final state. E.g:

STATE_5 == 
/\ items = {i1, i2, i3}
/\ json = "{\"init\": [\"i1\"], \"steps\": [{\"action\": \"Add\", \"item\": \"i3\"}, {\"action\": \"Add\", \"item\": \"i2\"}, {\"action\": \"Remove\", \"item\": \"i3\"}, {\"action\": \"Add\", \"item\": \"i3\"}], \"state\": [\"i1\", \"i2\", \"i3\"]}"
/\ trace = [ init |-> {i1},
  steps |->
      << [action |-> "Add", item |-> i3],
         [action |-> "Add", item |-> i2],
         [action |-> "Remove", item |-> i3],
         [action |-> "Add", item |-> i3] >>,
  state |-> {i1, i2, i3} ]

This can then be used to generate a test case by taking the start state, run the steps and comparing the end result with the end state, basically using TLC to generate input for property based testing.

Now the problem is that the above ToJsonObject call does not work because

• it only supports a small subset of TLA+ values.
• it does not support any nested structures
• it only supports integer keys and string values

I could just build a sequence of strings and use ToJsonObject on it, but being able to use arbitrary structures would be nice.

Also being able to export traces to other programs might have other interesting use cases.

Redefine restricted `SequencesExt!Zip`

SequencesExt!Zip(s,t) is currently defined only for Len(s) = Len(s). Let's replace its definition with a more universal one that discards the remainder of the longer input sequence.

  IF Len(s) < Len(t)
  THEN FoldLeft(LAMBDA acc, e: Append(acc, << e, t[Len(acc)+1] >>), <<>>, s)
  ELSE FoldLeft(LAMBDA acc, e: Append(acc, << s[Len(acc)+1], e >>), <<>>, t)

TLC fails to evaluate `Graphs!Path` because of `Seq`

(tla+) LET G == INSTANCE Graphs IN G!Path([node |-> {1,2,3}, edge |-> {<<1,2>>, <<2,3>>, <<3,1>>, <<1,3>>}])
{p \in Seq({1, 2, 3}) : <expression line 20, col 14 to line 21, col 68 of module Graphs> }

CommunityModules/modules/Graphs.tla

Line 19 in 6f9596b

Path(G) == {p \in Seq(G.node) :

For the definition AreConnected built on top of Path in Graphs, the new definition SimplePath based on SequencesExt!SeqOf(G.node, Cardinality(G.node)) should work.

Definition of SimplePath follows e.g. the "A directed path is simple if it has no repeated vertices." given in https://algs4.cs.princeton.edu/42digraph/.

Suppress warning about unmet Json dependency to when a spec uses the operators

The warning - introduced by commit b6e67a2 - should only be raised when a spec actually extends/instantiates the Json module. The majority of specs, however, won't extend or instantiate the Json module.

Make IOUtils compatible with Java 1.8

IOUtils.Java uses readAllBytes which were introduced in Java 9. We should try to get rid of it so the code is compatible with Java 1.8.

See #30 (review) for context.

Add URI-related operators to IOUtils

tlaplus/tlaplus@1eb8156#diff-364040e3b4487febdb3378d1e3a325421763d819b32c40520360494933a8e263R12 does not work for absolute paths. We should consider adding URI-related operators such as Dirname, Basename, Extname, ...

NoClassDefFoundError `: tlc2/value/impl/KSubsetValue` in Toolbox 1.7.1 CommunityModules.jar

I'm unable to run Model checking when I include the CommunityModules.jar file.

TLC threw an unexpected exception.
This was probably caused by an error in the spec or model.
See the User Output or TLC Console for clues to what happened.
The exception was a java.lang.NoClassDefFoundError
: tlc2/value/impl/KSubsetValue

java --version
openjdk 11.0.13 2021-10-19
OpenJDK Runtime Environment Temurin-11.0.13+8 (build 11.0.13+8)
OpenJDK 64-Bit Server VM Temurin-11.0.13+8 (build 11.0.13+8, mixed mode)

I'm also unclear on whether I should have the CommunityModules.jar, the CommunityModules-deps.jar, or both. Attempting to include any versioned module displays an error:
{0} is not a valid library path location

`Functions.tla` here clashes with `Functions.tla` in TLAPM

There is a name clash between the Functions.tla in CommunityModules and Functions.tla in TLAPM, with the Functions.tla in CommunityModules (CM!Functions.tla) having a superset of operators compared to the version in TLAPM. Users who open specs that depend on CM!Functions.tla but who have PM!Functions.tla on the library path (first) end up with an unparsable spec.

/cc @muenchnerkindl @xxyzzn

Likely related: tlaplus/tlapm#3

Json!JsonSerialize does not accept relative path

Inv == 
    \/ TLCGet("level") < 5 \* The ordinary invariant to check.
    \/ /\ JsonSerialize("trace.json", Trace) \* FAILS unless replaced with absolute path.
       /\ FALSE

Error: Evaluating invariant Inv failed.
Attempted to apply the operator overridden by the Java method
public static tlc2.value.impl.BoolValue tlc2.overrides.Json.serialize(tlc2.value.impl.StringValue,tlc2.value.impl.TupleValue) throws java.io.IOException,
but it produced the following error:
Cannot invoke "java.io.File.mkdirs()" because the return value of "java.io.File.getParentFile()" is null

LinkedList Module be useful?

One of the lessons in Practical TLA+ is making a linked list data structure. The entire module is online here: https://github.com/hwayne/practical-tla-plus/blob/master/Chapter%208/LinkedLists.tla

Happy to clean it up in anyway needed, just wanted to check if people think this would actually be useful to include. I don't know how specialized we want to go with these modules.

TLATester module

When building a spec I often found myself scratching my head at whether what I'd written corresponded to my mental model. I think the issue here is that TLA tries to keep the temporal logic part sane by only accepting LTL formulas as specs, while for incremental testing subsets of CTL are helpful, for example: "Is this sequence of steps possible?"

I don't know what best practices in this regard are, so I built a TLA boilerplate module which introduces additional variables in order to force a sequence of operators to be run in exactly the way I want them to.

Is this a potential candidate for inclusion in this repo or are there already better options available?

Add GraphViz module

Today the toolbox support dumping a trace in two pre-defined formats (TLA+ and Json) via the “dumptrace” option: https://github.com/tlaplus/tlaplus/blob/master/general/docs/current-tools.md#command-line-options.

Adding a support for GraphViz's DOT format will be super useful.

It would essentially require writing a GraphViz module that serializes a counterexample defined in TLA+ into GraphViz.

Copy useful modules/operators from TLAPS to CommunityModules

@muenchnerkindl suggested to copy useful operators from TLAPS:

• Merge SequencesExt and SequenceOps (where do I find SequenceOps?)
• Copy TLAPS to CommunityModules (as workaround to parser errors when users don't have TLAPS installed?!)

Add symmetric set difference operator

The symmetric difference of two sets can be a convenient operation to have around. FiniteSetsExt.tla seems a good place to add it. It can be defined as follows:

SymmDiff(A, B) == (A \ B) \cup (B \ A)

ShiViz module error because operator definition override not visible when instance marked local

I have been trying to use the ShiViz module in this spec without success. After I add either Host or Clock to the error-trace exploration I'm getting the following error (Toolbox version 1.7.1):

Error(s) from running the Trace Explorer:
Attempted to enumerate S \ T when S:
Nat
is not enumerable.
Error(s) from running the Trace Explorer:
TLC was unable to fingerprint.

Fingerprint Stack Trace:
1) line 14, col 21 to line 14, col 29 of module Toolbox
0) line 14, col 18 to line 14, col 42 of module Toolbox

Reason:
Attempted to enumerate S \ T when S:
Nat
is not enumerable.

Error seems to persist after overwriting Nat with 1..100.

Host and Clock from ShiViz module do not appear in error trace

As suggested in #37 (comment) I tried using ALIAS to make Host and Clock from the ShiViz module appear in the error trace. While ALIAS works in principle, it seems to get ignored as soon as I add Host or Clock:

---- CONFIG testAlias ----
SPECIFICATION Spec
INVARIANT NotTwo
ALIAS Alias
======================

----------------------------- MODULE testAlias -----------------------------
EXTENDS Integers, ShiViz

(*--algorithm testAlias
variables x=0;
begin
  x := 1;
  x := 2;
end algorithm; *)

\* BEGIN TRANSLATION (chksum(pcal) = "b3726e35" /\ chksum(tla) = "e9b2f587")
VARIABLES x, pc

vars == << x, pc >>

Init == (* Global variables *)
        /\ x = 0
        /\ pc = "Lbl_1"

Lbl_1 == /\ pc = "Lbl_1"
         /\ x' = 1
         /\ pc' = "Lbl_2"

Lbl_2 == /\ pc = "Lbl_2"
         /\ x' = 2
         /\ pc' = "Done"

(* Allow infinite stuttering to prevent deadlock on termination. *)
Terminating == pc = "Done" /\ UNCHANGED vars

Next == Lbl_1 \/ Lbl_2
           \/ Terminating

Spec == Init /\ [][Next]_vars

Termination == <>(pc = "Done")

\* END TRANSLATION

NotTwo == x /= 2
Alias == [
  test |-> x + 2,
  Host |-> Host
]
=============================================================================

Move DyadicRationals module from Weight-Throwing example

Move the module https://github.com/tlaplus/Examples/blob/master/specifications/Huang/DyadicRationals.tla here and add a definition DyadicRational (similar to Int, Nat, Reals) with an appropriate (Java) module override.

/cc @muenchnerkindl

Add an SVG!Table/Grid of Text

Most animations have an area where they show a table/grid that contains multiple Texts. The SVG module should have a definition for high-level Grid/Tables.

Support serializing to plain and newline-delimited JSON

State 1: <Initial predicate>
/\ active = (0 :> FALSE @@ 1 :> FALSE @@ 2 :> FALSE @@ 3 :> FALSE)
/\ color = (0 :> "white" @@ 1 :> "white" @@ 2 :> "white" @@ 3 :> "white")
/\ tpos = 3
/\ tcolor = "black"
/\ history = <<0, 0, "init">>

State 2: <AnimSystem line 26, col 3 to line 26, col 65 of module EWD840_anim>
/\ active = (0 :> FALSE @@ 1 :> FALSE @@ 2 :> FALSE @@ 3 :> FALSE)
/\ color = (0 :> "white" @@ 1 :> "white" @@ 2 :> "white" @@ 3 :> "white")
/\ tpos = 2
/\ tcolor = "black"
/\ history = <<0, 0, "PassToken">>

State 3: <AnimSystem line 26, col 3 to line 26, col 65 of module EWD840_anim>
/\ active = (0 :> FALSE @@ 1 :> FALSE @@ 2 :> FALSE @@ 3 :> FALSE)
/\ color = (0 :> "white" @@ 1 :> "white" @@ 2 :> "white" @@ 3 :> "white")
/\ tpos = 1
/\ tcolor = "black"
/\ history = <<0, 0, "PassToken">>

State 4: <AnimSystem line 26, col 3 to line 26, col 65 of module EWD840_anim>
/\ active = (0 :> FALSE @@ 1 :> FALSE @@ 2 :> FALSE @@ 3 :> FALSE)
/\ color = (0 :> "white" @@ 1 :> "white" @@ 2 :> "white" @@ 3 :> "white")
/\ tpos = 0
/\ tcolor = "black"
/\ history = <<0, 0, "PassToken">>

State 5: <AnimSystem line 26, col 3 to line 26, col 65 of module EWD840_anim>
/\ active = (0 :> FALSE @@ 1 :> FALSE @@ 2 :> FALSE @@ 3 :> FALSE)
/\ color = (0 :> "white" @@ 1 :> "white" @@ 2 :> "white" @@ 3 :> "white")
/\ tpos = 3
/\ tcolor = "white"
/\ history = <<0, 0, "InitiateProbe">>

State 6: <AnimSystem line 26, col 3 to line 26, col 65 of module EWD840_anim>
/\ active = (0 :> FALSE @@ 1 :> FALSE @@ 2 :> FALSE @@ 3 :> FALSE)
/\ color = (0 :> "white" @@ 1 :> "white" @@ 2 :> "white" @@ 3 :> "white")
/\ tpos = 2
/\ tcolor = "white"
/\ history = <<0, 0, "PassToken">>

{"color":{"0":"white","1":"white","2":"white","3":"white"},"tpos":3,"tcolor":"black","active":{"0":false,"1":false,"2":false,"3":false},"history":[0,0,"init"]}
{"color":{"0":"white","1":"white","2":"white","3":"white"},"tpos":2,"tcolor":"black","active":{"0":false,"1":false,"2":false,"3":false},"history":[0,0,"PassToken"]}
{"color":{"0":"white","1":"white","2":"white","3":"white"},"tpos":1,"tcolor":"black","active":{"0":false,"1":false,"2":false,"3":false},"history":[0,0,"PassToken"]}
{"color":{"0":"white","1":"white","2":"white","3":"white"},"tpos":0,"tcolor":"black","active":{"0":false,"1":false,"2":false,"3":false},"history":[0,0,"PassToken"]}

vs.

[
{"color":{"0":"white","1":"white","2":"white","3":"white"},"tpos":3,"tcolor":"black","active":{"0":false,"1":false,"2":false,"3":false},"history":[0,0,"init"]}
,
{"color":{"0":"white","1":"white","2":"white","3":"white"},"tpos":2,"tcolor":"black","active":{"0":false,"1":false,"2":false,"3":false},"history":[0,0,"PassToken"]}
,
{"color":{"0":"white","1":"white","2":"white","3":"white"},"tpos":1,"tcolor":"black","active":{"0":false,"1":false,"2":false,"3":false},"history":[0,0,"PassToken"]}
,
{"color":{"0":"white","1":"white","2":"white","3":"white"},"tpos":0,"tcolor":"black","active":{"0":false,"1":false,"2":false,"3":false},"history":[0,0,"PassToken"]}
]

https://medium.com/@kandros/newline-delimited-json-is-awesome-8f6259ed4b4b

---

Supported in Python3.8's json.tool with "--json-lines" (https://docs.python.org/3/library/json.html#cmdoption-json-tool-json-lines).

SVG!Group expects *sequence* of elements

CommunityModules/modules/SVG.tla

Lines 96 to 98 in dd64724

	(**************************************************************************)
	(* Group element. 'children' is a sequence of elements that will be *)
	(* contained in this group. *)

What is the meaning of the order given by the sequence? Is it the z coordinate of the svg?

Remove Json module

To prevent it from getting out of sync with the version in the standard modules. See tlaplus/tlaplus#764 (comment).